# Tekla MCP Server

This server facilitates interaction with Tekla Structures, helping users speed up modeling processes. It acts as a bridge between users and Tekla, enabling automated workflows and improving efficiency.

## 📌 What is MCP?

MCP stands for **Model Context Protocol**, a communication protocol introduced by Anthropic to enable more efficient and secure interactions between large language models and other systems.

Tekla MCP Server uses AI-powered natural language processing to make interactions more human-readable, allowing you to work with Tekla Structures using plain text commands.

## 🚀 Features

### Tools Available

| Tool | Description |
|------|-------------|
| `put_components` | Insert Tekla components into selected elements with custom properties |
| `remove_components` | Remove Tekla components from selected elements |
| `select_elements_by_filter` | Select elements by type, name, profile, material, finish, phase |
| `select_elements_by_filter_name` | Select elements using predefined filter names |
| `select_elements_by_guid` | Select elements by their GUID |
| `select_elements_assemblies_or_main_parts` | Get assemblies or main parts of selected elements |
| `draw_elements_labels` | Draw temporary labels showing element properties |
| `zoom_to_selection` | Zoom view to fit selected elements |
| `show_only_selected` | Show only selected elements in active view |
| `cut_elements_with_zero_class_parts` | Perform boolean cuts using class 0 elements |
| `convert_cut_parts_to_real_parts` | Convert cut geometry to real model parts |
| `set_elements_udas` | Set custom attributes on selected elements |
| `get_all_elements_udas` | Retrieve all custom attributes from elements |
| `get_elements_properties` | Get detailed element properties including weight and custom fields |

## 📋 Requirements

- **Tekla Structures 2023** (or compatible version)
- **Python 3.11 or newer**
- Required Python packages (see `requirements.txt`)

## 🔧 Installation

### 1. Install Dependencies

```bash
# Using uv (recommended)
uv pip install -r requirements.txt

# Using pip
pip install -r requirements.txt
```

⚠️ **Note**: You may experience a naming conflict with the `clr` string styling package. If this happens, rename or delete the folder:
```
C:\Users\<User>\AppData\Local\Programs\Python\Python311\Lib\site-packages\clr
```

### 2. Configure Settings

The configuration files are already set up for **Tekla 2023**. If you need to adjust paths:

1. Edit `config/settings.json`:
```json
{
  "tekla_path": "C:\\Program Files\\Tekla Structures\\2023.0\\bin",
  "content_attributes_file_path": "C:\\Program Files\\Tekla Structures\\2023.0\\bin\\applications\\Tekla\\Tools\\TplEd\\settings\\contentattributes_global.lst"
}
```

2. Customize `config/element_types.json` for your Tekla classes
3. Customize `config/base_components.json` with your component catalog numbers
4. Customize `config/lifting_anchor_types.json` for lifting anchor components

### 3. Set Up MCP Client

Configure `mcp_server.py` as a custom MCP server in your MCP client:

**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "tekla": {
      "command": "python",
      "args": ["d:\\VS\\TeklaMCPServer\\mcp_server.py"]
    }
  }
}
```

**For other MCP clients**: Consult your client's documentation for custom server configuration.

## 🧪 Testing

The project includes comprehensive unit and functional tests:

```bash
# Run all unit tests
uv run pytest tests/unit/

# Run all tests (functional tests skip if Tekla not running)
uv run pytest tests/

# Run specific test file
uv run pytest tests/unit/test_models.py

# Run functional tests (requires Tekla running)
uv run pytest tests/functional/ --run-functional
```

⚠️ **Warning**: Functional tests modify the actual Tekla model. Run them only in test/development environment.

## 📦 Distribution

Create a standalone executable using PyInstaller:

```bash
# Install PyInstaller
uv pip install pyinstaller

# Build executable
uv run pyinstaller mcp_server.py
```

The executable will be in `dist/mcp_server/`. Include the `_internals` directory when distributing.

**Note**: When using the executable, copy configuration files to `_internals/config/`.

## 💡 Usage Examples

### With Natural Language (via MCP Client)

```
"Select all beams with IPE300 profile and add lifting anchors"
"Get properties of selected columns"
"Show only elements in phase 1"
"Zoom to selected elements"
```

### Direct Tool Usage

The server exposes MCP tools that can be called programmatically:

```python
# Example: Select elements by filter
{
  "tool": "select_elements_by_filter",
  "arguments": {
    "element_type": "beam",
    "profile": "IPE300",
    "material": "S355"
  }
}
```

## 🔍 How It Works

### Architecture

```
┌─────────────────┐
│   MCP Client    │  (Claude Desktop, DeepChat, etc.)
│   (AI Model)    │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  mcp_server.py  │  ← Main server implementation
└────────┬────────┘
         │
         ├─→ models.py         (Data structures)
         ├─→ tekla_utils.py    (Tekla API wrapper)
         └─→ config/*.json     (Configuration)
                │
                ▼
         ┌──────────────┐
         │    Tekla     │  (via .NET API)
         │  Structures  │
         └──────────────┘
```

### Key Components

1. **MCP Server** ([mcp_server.py](mcp_server.py)): Handles MCP protocol communication and routes tool calls
2. **Tekla Utilities** ([tekla_utils.py](tekla_utils.py)): Wraps Tekla .NET API for Python access via pythonnet
3. **Data Models** ([models.py](models.py)): Pydantic models for type-safe data handling
4. **Configuration**: JSON files for customizing behavior per project

### MCP Protocol Integration

The server uses the `mcp` Python package to:
- Register available tools via `@app.list_tools()`
- Handle tool execution requests via `@app.call_tool()`
- Communicate over stdio with MCP clients
- Provide structured responses using Pydantic models

### Tekla API Usage

Tekla integration uses `pythonnet` (CLR) to:
- Load Tekla .NET assemblies dynamically
- Access Tekla.Structures.Model namespace
- Perform modeling operations (select, modify, insert components)
- Query element properties and user-defined attributes

## ✅ Verified Compatibility

**Tekla Version**: 2023

**MCP Clients**:
- DeepChat
- chatmcp

**AI Models**:
- GPT-4o
- DeepSeek
- Gemini 2.0 Flash
- Qwen3

## 📝 License

This software is open-source and released under the **GPLv3 license**. You are free to use, modify, and distribute it, as long as all modifications remain open-source under the same license.

See [LICENSE](LICENSE) for full details.

## ⚠️ Disclaimer

This software is provided **as is**, without any warranties or guarantees of functionality, reliability, or security. The developer assumes no responsibility for any damages, data loss, or other issues arising from its use.

**Use at your own risk.**

## 🤝 Contributing

Contributions are welcome! Please ensure:
- All tests pass before submitting PR
- New features include appropriate tests
- Code follows existing style conventions
- Configuration remains backward compatible

## 📞 Support

For issues and questions:
- Check existing GitHub issues
- Review test files for usage examples
- Consult Tekla API documentation for advanced usage

## 🗺️ Roadmap

Future enhancements (contributions welcome):
- Support for Tekla 2024+
- Additional intelligent components
- Enhanced filtering capabilities
- Drawing automation tools
- Report generation features