Metadata-Version: 2.4
Name: t4ea-mcp
Version: 0.1.0
Summary: Teamcenter Gateway (T4EA) API Reference MCP Server
License-Expression: MIT
License-File: LICENSE
Keywords: ai,api,claude,itk,mcp,plm,siemens,t4ea,teamcenter
Requires-Python: >=3.10
Requires-Dist: mcp>=1.26.0
Requires-Dist: uvicorn>=0.27.0
Description-Content-Type: text/markdown

# t4ea-mcp

MCP server that provides **Teamcenter Gateway for Enterprise Applications (T4EA)** API documentation to AI assistants. It enables AI coding tools like Claude, Cursor, and Windsurf to look up ITK functions, validate Tcl scripts, and navigate T4EA documentation accurately.

## Why

AI assistants frequently hallucinate function names and parameters when writing Teamcenter/T4EA code. This MCP server gives them access to the actual API reference, a function allowlist, and a script linter — drastically reducing errors in generated Tcl/ITK code.

## Installation

### From PyPI

```bash
pip install t4ea-mcp
```

### From source

```bash
git clone https://github.com/aldokruger/teamcenter-gateway-mcp.git
cd teamcenter-gateway-mcp
uv sync
```

**Requirements:** Python 3.10+

## Quick Start

### Run locally (stdio)

```bash
# Installed from PyPI
t4ea-mcp

# From source
uv run python -m t4ea_mcp
```

### Run as HTTP server

```bash
t4ea-mcp --http --port 8000
```

### Use the hosted version

A public instance is available at:

```
https://t4ea-mcp.fly.dev/mcp
```

## Connecting to Your AI Client

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "t4ea": {
      "command": "t4ea-mcp"
    }
  }
}
```

Or use the remote server:

```json
{
  "mcpServers": {
    "t4ea": {
      "url": "https://t4ea-mcp.fly.dev/mcp"
    }
  }
}
```

### Claude Code

```bash
claude mcp add t4ea -- t4ea-mcp
```

Or remote:

```bash
claude mcp add t4ea --transport http https://t4ea-mcp.fly.dev/mcp
```

### Cursor / Windsurf / VS Code

Add to your MCP settings (`.cursor/mcp.json`, etc.):

```json
{
  "mcpServers": {
    "t4ea": {
      "command": "t4ea-mcp"
    }
  }
}
```

## Tools

The server provides 9 tools:

| Tool | Purpose |
|------|---------|
| `resolve_topic` | **Start here** — routes natural language queries to the right docs |
| `search_docs` | Grep for exact strings across all documentation |
| `get_doc` | Read a specific documentation file (supports pagination) |
| `get_section` | Extract a section by markdown header |
| `list_docs` | List all available documentation files |
| `get_functions` | List valid T4EA/ITK functions by group |
| `validate_function` | Check if a function name exists in the allowlist |
| `get_manifest` | Get the LLM routing guide |
| `lint_script` | Lint Tcl/ITK scripts for errors and style issues |

### Recommended Workflow

1. **`resolve_topic("create item revision")`** — find relevant docs
2. **`get_functions("ITEM")`** — list valid ITEM functions
3. **`get_doc("modules/itk/item.md")`** — read the full reference
4. **`validate_function("ITEM_create_item")`** — verify before using
5. **`lint_script(your_code)`** — validate the generated script

### Linter Rules

The `lint_script` tool checks for:

| Rule | Severity | Description |
|------|----------|-------------|
| E001 | Error | Missing `package require` for used namespaces |
| E002 | Error | Deprecated function usage |
| E004 | Error | Removed/unsupported function usage |
| E005 | Error | Function not found in the T4EA allowlist (likely hallucinated) |
| W001 | Warning | Missing `ITK_ok` check after ITK calls |
| W002 | Warning | Missing `ITK::isITK_ok` guard pattern |

## Documentation Coverage

The server bundles comprehensive T4EA reference documentation:

- **42 ITK modules** — AOM, BOM, ITEM, EPM, AM, POM, and more
- **23 utility modules** — base64, SQL, SOAP, HTML/XML, encryption, etc.
- **100+ namespaces** — pipeline, configuration, OAuth2, monitoring, pl4x, and more
- **7 class references** — PipelineStep, StepParameter types, Function
- **Function allowlist** — JSON index of all valid T4EA/ITK function names

## Deployment

### Fly.io

```bash
fly deploy
```

The included `Dockerfile` and `fly.toml` are preconfigured for Fly.io deployment with auto-suspend and health checks.

### Docker

```bash
docker build -t t4ea-mcp .
docker run -p 8080:8080 t4ea-mcp
```

## Development

```bash
# Run in development
uv run python -m t4ea_mcp

# Run HTTP mode for testing
uv run python -m t4ea_mcp --http --port 8000

# Bump version
uvx bump-my-version bump patch

# Build and publish
uv build && uvx twine upload dist/*
```

## License

MIT
