MCP Civil Tools

You can run and interact with an MCP-based Civil Tools server to query and compute civil engineering data and coordinate transformations using natural language via supported MCP clients. This server exposes tools for Manning coefficients, soil pressure, drainage hydraulics, slope stability, erosion, runoff, retaining wall checks, vegetation guidance, material parameters, slope protection, infiltration facilities, IDF curves, and coordinate conversions for Taiwan. It is designed to work with MCP-enabled tools and AI assistants, and it’s important to validate results in real-world applications since model outputs may vary.

How to use

You will connect to the server using an MCP client configuration and then issue queries in natural language. The server can run in two modes: a local stdio server that you start from your environment, and an HTTP service you can call from API clients or test suites. In both modes you will access the same set of tools and capabilities, including coordinate transformations, Manning coefficient lookups, soil and slope analyses, runoff calculations, and design checks for drainage and retaining structures.

Typical usage flows include: asking for coordinate conversions (latitude/longitude to UTM and back), requesting material properties (Manning n, shear strength, friction angles), performing USLE factor lookups, calculating catchment runoff for a given rainfall event, designing and checking drainage channels, and getting vegetation or slope protection recommendations. You can also request automated reports that include the calculation steps and formulas used.

How to install

Prerequisites: ensure Python is installed on your system. It is recommended to use a virtual environment to isolate dependencies.

Step-by-step commands:

Install commands

python -m venv .venv
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # Linux/macOS

pip install -r requirements.txt

# Start in stdio (CLI) mode
python src/mcp_server.py

# Start in HTTP service mode (recommended for API testing)
uvicorn src.mcp_server:app --port 8000

Other important notes

You can configure the MCP server to launch automatically from an MCP client by providing an MCP setting JSON that points to the Python executable in your virtual environment and the path to the mcp_server.py script. Windows and macOS examples are provided to help you prepare the exact command line for your environment.

Configuration and security

The server supports local execution via stdio and an HTTP interface for remote calls. When running in HTTP mode, ensure you secure access to the endpoint, use appropriate authentication if you connect from untrusted networks, and validate all inputs before relying on results in production.

Troubleshooting and notes

If you encounter issues, verify that your Python virtual environment is active, dependencies are installed, and the correct start command is used for your chosen mode. If results seem off, re-check inputs or run a smaller, well-defined test case to confirm basic functionality before scaling up.

Examples and quick references

The server supports a wide range of tools and endpoints. Common tasks include coordinate conversions, Manning coefficient lookups, soil-erosion indices, USLE factor queries, and channel flow calculations. Use plain language descriptions to request what you need, and the server will route your query to the appropriate tool and return the results along with a concise explanation.

Available tools

list_supported_materials

Return a list of commonly used materials and their design parameter names.

list_supported_manning_materials

Return materials for which Manning n-values are defined.

list_supported_max_velocity_materials

Return materials with defined maximum allowable flow velocities.

list_supported_regions

Return regions, IDF locations, and rainfall data groupings.

list_supported_soil_types

Return soil type categories available for design checks.

list_supported_land_uses

Return land use types used for runoff and erosion analyses.

list_supported_practices

Return soil and water conservation practices available in the system.

list_supported_runoff_land_uses

Return land uses used to determine runoff coefficients.

list_supported_slope_protection_methods

Return slope stabilization methods available in the catalog.

list_supported_soil_k_types

Return soil erosion factor (K) types with corresponding values.

list_supported_idf_locations

Return IDF curve locations available for rainfall intensity lookup.

query_r_factor_tool

Query rainfall erosivity factor R from the USLE framework per guidelines.

query_k_factor_tool

Query soil erodibility factor K from soil data.

query_c_factor_tool

Query cover-management factor C for different land uses.

query_p_factor_tool

Query erosion control factor P for farming and terracing practices.

calc_catchment_runoff

Compute maximum runoff for a given catchment area and rainfall scenario.

check_retaining_wall

Evaluate static and seismic safety factors for retaining walls and provide a stability report.

calc_channel_section_flow

Calculate cross-section flow properties (velocity, depth, area) for drainage channels.

gabion_stability_check

Analyze stability of gabion walls including active/passive earth pressures.

design_vegetation_slope_protection

Provide vegetation-based slope stabilization recommendations.

design_soil_pipe

Estimate pipe drainage design parameters and required reinforcement for concrete channels.