kompas3d-mcp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project goal

An MCP (Model Context Protocol) server that lets an LLM drive the CAD system КОМПАС-3D (ASCON). The server is a COM client of an installed КОМПАС: it exposes CAD operations (documents, 2D sketches, 3D parts, assemblies, drawings, STEP round-trip, model inspection) as MCP tools over stdio.

There is no docs/ directory — it was deleted deliberately (commit b022a91). Do not re-create docs/ARCHITECTURE.md, docs/TODO.md, docs/OPEN_QUESTIONS.md. Prose documentation lives in exactly three places: this file (always loaded — architecture, principles, backlog, traps), the skill kompas-mcp-dev with reference/*.md (loaded on demand — verified COM call-chains, release and CI), and README.md (the tool catalog). Plus the memory files (kompas-*-api*.md).

Authoritative API references:

• SDK knowledge base in RAG: MCP server kompas-sdk — 2465 articles (one per COM interface/topic), served from the separate kompas-sdk-docs repo, indexed on CT 127 (rag-node). Not in this repo — Grep/Read won't find it. For any lookup dispatch the kompas-sdk-research subagent (Haiku), which owns the MCP tools.
• Online SDK docs: https://help.ascon.ru/KOMPAS_SDK/22/ru-RU/index.html
• Local SDK install: C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK (headers Include\ksConstants*.h are the last word on numeric constant values)
• libs/kompas-interop/*.dll — reflect over these to verify any signature a research answer gives you.

The base covers the COM API7/API5 reference this project uses; the cross-platform Qt/C++ KsAPI flavour (ksapi_*, non-COM) is intentionally excluded — ignore unless explicitly working with KsAPI. How to search it is in the subagent's own definition (.claude/agents/kompas-sdk-research.md) — those tools are scoped to the subagent, this session cannot call them. How to regenerate the base when a new КОМПАС ships — skill kompas-mcp-dev, reference/plugin-and-release.md.

Current state

Status: working end-to-end. Parts (sketch → feature → inspect), forming ops, patterns/mirror, holes, direct B-rep edit, STEP import/export, assemblies, 2D drawings, structural inspection — implemented and validated live. Also packaged as the Claude Code plugin kompas (no release published yet).

The full tool catalog (by group) lives in README.md §«Инструменты» — the single source of truth; do not duplicate it here.

dotnet build -c Release                          # build
dotnet test  --filter "Category=Unit"            # no COM needed
dotnet test  --filter "Category=Integration"     # needs a running КОМПАС
dotnet run --project src/Kompas.Mcp.Host         # start the MCP server (stdio)
pwsh -NoProfile -File tools/tests/run-ps-tests.ps1   # Pester tests for the plugin's PowerShell

Principle: MCP = translating SDK capabilities into general tools, never task-specific ones. If a technique is missing, don't hardcode a workaround for the case at hand — prove the mechanism, then add a general tool with tests, and describe the method in the kompas-3d skill.

Backlog (canonical since docs/TODO.md is gone)

• 2D drawing (top priority): bases (drawing_add_base), tolerances, associative binding for arc/angular/rough dimensions (needs its own spike — ILineDimension has no BaseObject).
• Assembly: mate types beyond coincidence/distance — parallel, perpendicular, concentric, angle, tangency (enum values exist in MateType.cs, not verified live).
• Known caveat: boss/cut direction on a selected face depends on the face-normal orientation — forward may need flipping. Pick the direction from describe_face normal or a snapshot before building.

Skills and their layout

• kompas-3d — methodology for building things through the MCP tools (playbooks, heuristics).
• kompas-fdm-design — DFM layer for FDM/FFF printing (overhang rules, wall thickness, teardrop holes, fits/clearances, orientation for strength, elephant foot, bosses/inserts/snap-fits) plus a light geometry audit via the inspection tools. Builds through kompas-3d, exports via export_step, no slicer integration.
• kompas-mcp-dev — internal: developing the server itself (the two layers, the usecases/ proving ground, the checklist for productizing a technique into a general tool, delegation). Lives at .claude/skills/kompas-mcp-dev/SKILL.md as a real directory (not a junction) because the published skills must not reference things a plugin user doesn't have.

Sync (tools/sync-agent-assets.ps1, module tools/AgentAssets.psm1): the source of truth is plugin/skills/{kompas-3d,kompas-fdm-design}; .claude/skills/<name> and .agents/skills/<name> are junctions onto it created by the script (their paths are pinpointed in .gitignore — git sees a junction as a plain directory). Its modes are mutually exclusive parameter sets, so -Remove -Check together is a parameter-binding error.

Gotcha: switching to a branch/commit predating plugin/skills leaves the junctions dangling and git checkout fails mid-way (unable to create file .claude/skills/kompas-fdm-design/SKILL.md: No such file or directory) — part of the worktree is already deleted while HEAD stays on the old branch. Recover with git ls-files --deleted -z | xargs -0 git restore --. Correct order:

1. pwsh -NoProfile -File tools/sync-agent-assets.ps1 -Remove
2. git checkout <ref>
3. pwsh -NoProfile -File tools/sync-agent-assets.ps1 (re-link, if plugin/skills exists on that ref)

-Remove is safe: it deletes the reparse point itself via [System.IO.Directory]::Delete (no -Recurse), never walks into the target, and leaves a real (non-junction) directory alone (Skipped); it detects a junction by the ReparsePoint attribute rather than by resolving the target, which is exactly why it still works once the target is gone. No post-checkout hook on purpose — it fires after checkout already broke, too late to help.

Delegation subagent

kompas-sdk-research (.claude/agents/, model Haiku, read-only — MCP kompas-sdk tools only): finds an interface/method/enum/constant signature in the SDK knowledge base and returns a compressed summary. Dispatch it for any SDK lookup — it holds the only access to the base, which no longer lives in this repo. Its system prompt is in the agent definition, so pass only the question as the prompt. A wrong answer is cheap: re-verify against libs/kompas-interop/*.dll by reflection.

(The former docs-maintainer subagent was removed together with docs/ — edit README.md/CLAUDE.md directly.)

Claude Code plugin (plugin/)

The server and both published skills ship as the plugin kompas — plugin/ is a self-contained tree, distributed independently of the rest of the repo, released from the dist branch (never main).

Manifest/lock layout, the delivery bootstrap, the launcher's stdout invariant, the release workflow and the CI gotchas — skill kompas-mcp-dev, reference/plugin-and-release.md. Two rules that must not wait for a skill load:

• Every release must bump plugin/.claude-plugin/plugin.json — the version is Claude Code's cache key, and /plugin update silently skips a plugin whose version already matches what's installed.
• Plugin PowerShell files must be UTF-8 with BOM. The launcher runs under Windows PowerShell 5.1, which reads BOM-less files in the system ANSI codepage — Cyrillic string literals then corrupt parsing of the whole script. pwsh 7 doesn't reproduce this, so it passes locally and breaks for the user.

Key implementation facts (don't relearn)

Verified COM call-chains — interop loading, the STA dispatcher, API5 ksPart building, face/edge selection, МЦХ, snapshots, the feature tree, variables, STEP round-trip, direct B-rep edit, forming ops, patterns and mirror, holes, assemblies, 2D drawings, sketch primitives — live in skill kompas-mcp-dev, reference/com-implementation-facts.md. Load that skill before touching the COM layer; append to it when a new chain is verified live. Cross-checked duplicates also sit in memory (kompas-*-api*.md).

КОМПАС-3D API architecture (the critical context)

КОМПАС-3D is automated via a COM Automation API, Windows-only. КОМПАС must be installed and running/launchable on the same machine — the MCP server is a COM client, not a standalone CAD engine. Two API generations coexist:

	Entry point	Namespace (C#)	Style	Use when
API5 (legacy)	KompasObject	Kompas6API5	procedural, flat	3D ksPart building, 2D primitives, bootstrapping
API7 (modern, preferred)	IApplication / _Application	KompasAPI7	OOP, interface-based	documents, holes, assemblies, drawings, B-rep edit

Constants live in separate libraries: Kompas6Constants, Kompas6Constants3D (C#), or ksConstants.h / ksConstants3D.h (C++).

Connection pattern (verified from Samples/CSharp.zip)

1. Get the КОМПАС root object by COM ProgID. Verified on this machine (v24 Home): KOMPAS.Application.7 and KOMPAS.Application.5 are registered; KOMPASLT.* is absent — the Home edition uses the regular (non-LT) ProgIDs. Resolution order:
   • KOMPAS.Application.7 — direct API7 IApplication (preferred)
   • KOMPAS.Application.5 — API5 KompasObject, then ksGetApplication7()
   • KOMPASLT.Application.5 — fallback for other installations
   • New instance: Activator.CreateInstance(Type.GetTypeFromProgID(progId))
   • Attach to a running instance: Marshal.GetActiveObject(progId)
2. If you entered via API5, obtain the modern application: IApplication appl = (IApplication)kompas.ksGetApplication7();
3. Set appl.Visible = true to show the КОМПАС window; drive documents via API7 interfaces (IKompasDocument2D, IKompasDocument3D, …).

The SDK C# samples are mostly КОМПАС plugin libraries (DLLs loaded into КОМПАС as ActiveX, entry methods like ExternalRunCommand/ExternalMenuItem, registered via [ComRegisterFunction]). This server is the opposite direction: a standalone external automation client connecting out-of-process via the ProgID pattern above. Read the samples for API usage, not for the plugin packaging/registration boilerplate.

SDK layout (read-only reference, not part of this repo)

The SDK tree under C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK (lib\*.tlb, lib64\, Include\, KsAPI\, Samples\*.zip, Help\KOMPAS_SDK_ru-RU.zip) is one ls away — browse it rather than trusting a copy here. Two things that are not visible from a listing:

To inspect a sample without unpacking the whole archive: unzip -p "<path>\Samples\CSharp.zip" "Automation/Step2_API7_3D/Step2_API7_3D.cs". The .cs sample sources are Windows-1251 encoded (Cyrillic comments appear garbled in UTF-8 tools).

Conventions / gotchas

• Windows-only & 64-bit: target x64 to match the installed КОМПАС; mixing bitness breaks COM activation. v24 Home is the installed edition — some full-edition API features may be unavailable.
• Encoding: SDK sources are CP1251; project files are UTF-8; plugin PowerShell is UTF-8 with BOM.
• COM lifetime: release COM objects (Marshal.ReleaseComObject) or scope them; a leaked reference keeps the КОМПАС process alive.
• API choice: prefer API7 for new tools; drop to API5 only for what API7 doesn't expose.
• Sequential tool calls: the build session keeps sketches by id and the server serves requests concurrently — dependent tool calls must be awaited one at a time.