Skip to main content
Glama
fcoh

fcoh

by SoseiUncle

FCOH — Feature-Centric Operation History

v0.1.0 / Experimental preview / MIT License / 無料・サポート保証なし

FCOH(Feature-Centric Operation History)形式0.3の最小試作です。 設計意図つきYAMLから、新しい部品をFreeCADまたはFusionで作ります。 ソフトウェアの版番号は0.1.0、実装している形式の版番号は0.3です。 汎用CADファイル変換ソフトではなく、CADに依存しない設計意図・操作履歴の記録と再現を試すOSSです。

FCOH is an experimental, human/LLM-readable YAML representation of CAD design intent and operation history, replayed through native FreeCAD and Autodesk Fusion APIs. It is not a general CAD file converter or a complete round-trip interchange format.

2026-09-13: 両CADへのMCP経由の部品生成と、ネイティブ形式保存・再読込が成功しました。 サンプルのSTEP同士の形状差分も0 mm³でした。検証概要を参照してください。

ライセンス・サポート

本プロジェクトのソースコードはMIT Licenseで無償公開しています。 現状有姿で提供し、保証、個別サポート、返信、修正、継続保守の約束はありません。 製造や実務で使う前に、生成形状・寸法・履歴を利用者自身で検証してください。 FreeCAD、Autodesk Fusion、Python依存パッケージなどの第三者製品には、それぞれのライセンスが適用されます。 Fusion本体は同梱せず、その利用権や無償利用を提供するものではありません。

Related MCP server: freecad-tool-server

初回セットアップ(Windows x64)

PowerShell 7、Git、Python 3.11以上、uv、7-Zipを用意してください。 7-Zipは C:\Program Files\7-Zip\7z.exe にあることを前提とします。 Fusion連携は別途Autodesk Fusionをインストールし、利用可能なアカウントで起動しておきます。

git clone https://github.com/SoseiUncle/fcoh.git
cd fcoh
pwsh -File scripts/setup.ps1
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

セットアップはFreeCAD 1.1.3公式ポータブル版をダウンロードし、SHA-256を照合して vendor/ へ展開します。Python依存は uv.lock に従って .venv/ へ導入します。 このリリースはソースチェックアウトから使用してください。単体wheel/PyPI配布には対応していません。 フォルダを移動した場合はFusionアドインとMCPの登録をやり直してください。

使い方

このフォルダをVS CodeやCodexのプロジェクトとして開いてください。 コマンドはPowerShell 7で、このフォルダから実行します。 サンプルの生成だけなら Generate-FreeCAD.cmd または Generate-Fusion.cmd を ダブルクリックしても実行できます。Fusion用はFusionを開いた状態で使います。

.\.venv\Scripts\python.exe -m fcoh.cli validate examples/mounting-bracket.fcoh.yaml
.\.venv\Scripts\python.exe -m fcoh.cli build examples/mounting-bracket.fcoh.yaml --cad freecad

生成先は毎回別の outputs/<job_id>/ です。FreeCADでは part.FCStd と part.step、 Fusionでは part.f3d と part.step を保存します。request.json に実行内容、 source.fcoh.yaml に入力の写し、result.json に寸法・体積・履歴・ハッシュを残します。

サンプルは80×40×30 mm、底板厚6 mm、直径6 mmの穴4個を持つブラケットです。 examples/mounting-bracket.fcoh.yaml の params の数値を変更し、再生成してください。 寸法の正本はFCOHです。CAD内で変更した寸法を自動的にFCOHへ戻す機能はありません。

Fusion

初回は次のコマンドでFcohBridgeをユーザー用AddInsフォルダへ導入します。

pwsh -File scripts/install-fusion.ps1

その後Fusionを再起動し、「ユーティリティ → スクリプトとアドイン → アドイン」で FcohBridge を選び、「実行」「起動時に実行」を有効にします。

Fusionのモデリング画面で、実行中の編集コマンドを完了またはキャンセルしてから:

.\.venv\Scripts\python.exe -m fcoh.cli capabilities
.\.venv\Scripts\python.exe -m fcoh.cli build examples/mounting-bracket.fcoh.yaml --cad fusion --wait 180

アドインはローカルの .runtime/queue/ を読み、FusionのCustomEventでメインスレッドへ処理を渡します。 通信ポートやクラウド保存は使用しません。Fusion自体の通常のログイン・ライセンス通信は必要です。 生成文書はFusion上に開いたまま残り、アーカイブはローカルに保存されます。 ジョブは10分で期限切れになり、期限後には生成しません。

生成ロジックはジョブごとにこのプロジェクトの固定パスから読み込みます。 ブリッジ本体を更新したときは scripts/install-fusion.ps1 を実行し、Fusion本体を再起動してください。 この環境ではアドインの停止・実行だけだと古いPythonコードが残ることを実機確認しています。 導入済みアドインは更新前に .runtime/backups/ へ保存します。

Codex / MCP

Codex CLIを利用する場合、次でユーザー設定に fcoh として登録できます。

pwsh -File scripts/register-mcp.ps1

新しく開くセッションで利用してください。既存の会話へツールが自動追加されるとは限りません。 通し検証スクリプトは同じ起動コマンドへstdioで接続します。

ツール

用途

fcoh_capabilities

対応範囲、FreeCADの配置、Fusionアドインの起動応答を確認

fcoh_validate(file)

YAMLの型・単位・参照・操作順を検証

fcoh_build(file, cad)

新しい部品を生成。FusionはジョブIDを返す

fcoh_status(job_id)

結果・生成ファイル・計測値を取得

依頼例: 「examples/mounting-bracket.fcoh.yamlを検証して、FreeCADで新規部品を生成してください。」

別のMCPクライアントでも、次のコマンドをstdioサーバーとして登録できます。

command: <absolute-path-to-fcoh>\.venv\Scripts\python.exe
args: ["-m", "fcoh.server"]

再登録は scripts/register-mcp.ps1、Codex登録の解除は codex mcp remove fcoh です。

検証

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe scripts/verify_mcp.py --cad freecad
.\.venv\Scripts\python.exe scripts/verify_geometry.py
.\.venv\Scripts\python.exe scripts/verify_mcp.py --cad fusion
.\.venv\Scripts\python.exe scripts/verify_cross_cad.py

evidence/ に通し検証の結果を保存します(PC固有パスを含むためGit管理対象外)。 Fusion用の検証はアドインが動作している必要があります。 MCP検証では、部品体積を幾何学的な計算値と比較し、外形寸法、ソリッド数、操作順、 出力ファイルの実在とハッシュ、元YAMLが変更されないことを確認します。 FreeCADでは保存後のFCStdとSTEP再読込、FCOHメタデータ保持も検証します。 FusionでもF3Dを再読込して形状・履歴・FCOH属性を確認します。 両CADの成功後、STEP同士の差分ソリッド体積を比較します。

現在の対応範囲

  • 単位mm、単一部品、XY基準面とZオフセット。

  • 矩形・円の閉じたスケッチ、+Z押し出し、-Zポケット。

  • meaning / why とFCOH IDをCAD内のプロパティ/属性へ保存。

  • FreeCADではSpreadsheet、Fusionではユーザーパラメータにも寸法を保存。

  • 押し出し長さはCADの名前付きパラメータに結び付ける。輪郭全体の寸法変更はYAMLから再生成する。

未対応の指定はエラーにします。STEP/STL入力、フィレット、面取り、スケッチ拘束の一般化、 アセンブリ、既存CAD履歴の抽出、完全な往復変換、CAD内の編集結果のFCOHへの書き戻しは未対応です。 このスキーマはFCOH全仕様を確定したものではなく、実行できる最初の部分集合です。

構成と再現

fcoh/ は共通処理、schemas/ はスキーマ、adapters/ はCADごとの処理です。 セットアップ後、vendor/ にFreeCADポータブル版、.venv/ に専用Python環境が作られます。 依存関係は uv.lock へ固定し、OS全体のMCP SDKは変更していません。

再構築はPowerShell 7、uv、7-Zipを用意して scripts/setup.ps1 を実行します。 FreeCAD公式アーカイブのSHA-256を照合してから展開します。

参照: FreeCAD公式配布、 Fusion CustomEvent公式例、 MCP Python SDK、 Codex MCP設定。

Available Tools

4 tools
fcoh_buildA

Create a NEW part under outputs/<job_id>. cad: freecad or fusion. Fusion is asynchronous; use fcoh_status.

Inputs: file (required), cad.

fcoh_capabilitiesA

Report supported FCOH steps and actual CAD adapter readiness.

Inputs: no named parameters.

fcoh_statusB

Read CAD generation status, measured geometry, and exported artifact paths.

Inputs: job_id (required).

fcoh_validateA

Validate a project-relative .fcoh.yaml file without creating a CAD document.

Inputs: file (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool serves a distinct function: capabilities reports environment, validate checks config, build initiates creation, status tracks progress. No overlapping purposes or ambiguous boundaries.

    Naming Consistency5/5

    All tools follow a consistent 'fcoh_<verb>' pattern, making the API predictable and easy to navigate. The verb choice clearly indicates the operation.

    Tool Count5/5

    Four tools is well-scoped for a focused CAD generation pipeline—enough to cover the essential steps without redundancy or bloat.

    Completeness4/5

    The set covers the core workflow: capability check, validation, build, and status. Minor gaps like cancellation or listing are absent, but the primary lifecycle is complete for a simple create-and-monitor use case.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to programmatically build, analyze, and export 3D CAD geometry using FreeCAD through REST or MCP tools.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and software to create, edit, inspect, validate, and export CAD geometry through MCP using backend-neutral typed operations, with FreeCAD/OpenCascade as the authoritative B-rep backend and JSCAD preview.
      1
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to create, edit, and export CAD models and drawings in a locally installed FreeCAD via MCP.
      3
      -