# OpenFab MCP

[English](README.md) | [简体中文](README.zh-CN.md)

**An open-source MCP toolkit for industrial manufacturing workflows, starting with FANUC robot programs and STEP CAD files.**

OpenFab MCP v0.1.0 is an offline-first engineering toolkit. It turns common manufacturing engineering files into structured, auditable data and exposes the same capabilities through Python integration functions, a CLI, and an MCP server.

## Problem

AI coding agents can already work effectively with source code and developer tooling, but traditional manufacturing engineering files and offline robot programs still lack an open, standardized, auditable tool layer for agents.

OpenFab starts with two practical formats:

- FANUC `.LS` robot program source
- STEP / STP CAD files

The goal of v0.1.0 is not robot control. It is a small, inspectable **offline engineering workflow** for parsing, analysis, linting, and draft generation.

## Architecture

```text
Codex / Claude / MCP Clients
            ↓
       OpenFab MCP
       /         \
    FANUC        CAD
      ↓           ↓
   .LS files   STEP/STP
```

Internally, the CLI and MCP server share the same service boundary:

```text
CLI ─┐
     ├→ services.py → FANUC / STEP
MCP ─┘
```

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the integration design.

## Current capabilities

### FANUC `.LS`

- parse `.LS` source
- inspect program structure
- preserve source-oriented program semantics without aggressive guessing
- lint `UFRAME_NUM`, `UTOOL_NUM`, and `P[...]` references
- detect missing and duplicate positions
- check `J` / `L` motion forms
- check basic speed formats
- check `CNT` / `FINE` termination forms
- generate explicitly offline `.LS` drafts from structured input

### STEP / STP

- STEP schema and selected Part-21 header metadata
- topology counts: solids, shells, faces, edges, wires, vertices, compsolids, compounds
- bounding box
- overall X / Y / Z dimensions
- volume when reliably available
- center of mass when reliably available
- basic B-Rep statistics such as surface area and total edge length

STEP geometry is handled by Open CASCADE Technology through the `cadquery-ocp-novtk` package. See [`docs/CAD_STEP_LIMITS.md`](docs/CAD_STEP_LIMITS.md) for explicit limits.

### MCP tools

- `step_analyze`
- `fanuc_parse_ls`
- `fanuc_lint_ls`
- `fanuc_generate_ls_draft`

### CLI commands

```bash
openfab fanuc parse <file.ls> [--json]
openfab fanuc lint <file.ls> [--json]
openfab fanuc generate <draft.json> [-o output.ls] [--json]
openfab step analyze <file.step|file.stp> [--json]
openfab --version
```

The MCP stdio entry point is:

```bash
openfab-mcp
```

## Installation

OpenFab requires Python 3.11 or newer.

Base install: MCP server, CLI, and FANUC text functionality. This does **not** install OCCT/OCP.

```bash
pip install -e .
```

Add STEP/STP analysis:

```bash
pip install -e ".[step]"
```

Install all OpenFab runtime functionality:

```bash
pip install -e ".[all]"
```

For development and tests, install runtime functionality plus development tools:

```bash
pip install -e ".[all,dev]"
```

## Examples

Parse a known-good offline FANUC example:

```bash
openfab fanuc parse examples/fanuc/sample_ok.ls --json
```

Lint the intentionally malformed example:

```bash
openfab fanuc lint examples/fanuc/sample_bad.ls --json
```

Generate an offline draft from structured JSON:

```bash
openfab fanuc generate examples/fanuc/draft.json -o openfab_draft.ls
```

Analyze the included 10 × 20 × 30 mm STEP box:

```bash
openfab step analyze examples/step/box_10x20x30.step --json
```

The repository examples are synthetic/offline fixtures and are not real production robot programs.

## MCP server

Start the stdio server:

```bash
openfab-mcp
```

The server exposes the same integration functions used by the CLI. MCP protocol tests use the official MCP Python SDK v2 in-memory client (`from mcp import Client`) against the server object directly.

See [`docs/API.md`](docs/API.md) for the current data/API notes.

## Safety

OpenFab MCP v0.1.0 is designed for offline engineering analysis and draft preparation.

It:

- does not connect to real FANUC controllers
- does not upload programs
- does not execute robot motion
- does not validate reachability
- does not validate collision safety
- does not validate DCS or other safety systems
- treats generated LS output as an offline draft only

**Generated robot programs require review and validation by qualified personnel using appropriate FANUC tooling and simulation before any real-world use.**

## Testing

The release CI installs dependencies in a clean environment and runs the full test suite on Python 3.11, 3.12, and 3.13 on Ubuntu, plus Python 3.12 on a GitHub-hosted macOS ARM64 runner.

Local release checks:

```bash
pip install -e ".[all,dev]"
pytest
python -m compileall src
python -m build
```

## Documentation

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- [`docs/API.md`](docs/API.md)
- [`docs/CAD_STEP_LIMITS.md`](docs/CAD_STEP_LIMITS.md)
- [`docs/THIRD_PARTY_LICENSES.md`](docs/THIRD_PARTY_LICENSES.md)
- [`SECURITY.md`](SECURITY.md)
- [`CONTRIBUTING.md`](CONTRIBUTING.md)

## License

OpenFab MCP is licensed under the Apache License 2.0. See [`LICENSE`](LICENSE).

Third-party components retain their own licenses and copyright. See [`docs/THIRD_PARTY_LICENSES.md`](docs/THIRD_PARTY_LICENSES.md).