TcKit

An MCP server that gives AI agents a precise, structured view of a TwinCAT 3 project — and the tools to change, build, and test it.

---

Why TcKit

LLMs do not get smarter when you give them more tokens. Quality degrades as context fills up — Anthropic call this context rot, and PLC projects are an unusually fast way to trigger it: a single .TcPOU file is XML wrapped around code, easily thousands of lines for one function block. Pasting one in to ask about one method poisons the rest of the conversation.

TcKit is the layer in between. Instead of dumping files at the model, it exposes six capabilities shaped around the patterns Anthropic recommend for agent tools: layered just-in-time reads, a single source of truth for writes, and structured results from builds and tests.

---

What it solves

Problem	What goes wrong without it	TcKit's answer
Context rot as tokens accumulate	Whole-POU paste to ask about one method	ProjectReader — three precision levels
Pre-loading vs just-in-time retrieval	Stuffing manuals into context "just in case", or hallucinating vendor FB signatures	DocsSearcher — fetch one page on demand
Drifting sources of truth	Hand-edited XML diverging from project cross-refs	ProjectWriter — IDE stays authoritative
Unstructured tool output	Scraping raw logs for the one line that matters	BuildRunner + TestRunner — parsed results
Stable surface under churn	Re-prompting when the underlying tooling shifts	Ports & adapters — swap the adapter, tool shape stays
Code as source of truth for docs	Drifting wikis next to authoritative code	DocGenerator — render docs from ST comments

---

Capabilities at a glance

Port	What it does	State
ProjectReader	Read POUs, interfaces, methods, GVLs, DUTs at three precision levels	Complete
DocsSearcher	Fetch vendor documentation pages on demand	Complete
DocGenerator	Render docs from comments in ST source	Complete
ProjectWriter	Structural writes via the IDE's authoring interface	In progress
BuildRunner	Build, deploy, runtime control with structured diagnostics	In progress
TestRunner	Run unit tests, return parsed suite/test trees	Planned

---

Quick start

git clone https://github.com/turb5/tckit
cd tckit

cp docker/.env.example docker/.env
# Edit docker/.env with your paths

docker compose -f docker/docker-compose.yml up

Then add TcKit to your MCP client config:

{
  "mcpServers": {
    "tckit": {
      "url": "http://localhost:8000/sse"
    }
  }
}

See Getting Started → Installation for the full setup, including the Windows bridge for write/build/test operations.

---

Design philosophy

TcKit uses a ports & adapters (hexagonal) architecture. Every external concern is abstracted behind a port (Python ABC). Adapters implement ports. The MCP server only calls ports.

The one hard rule: adapters may only import from ports and stdlib. Never from each other.

This means when the underlying tooling changes — a new IDE COM version, a new build CLI, a different docs source — you write a new adapter and change one config value. The port contract, and therefore the agent-facing tool surface, does not change.

See Architecture → Overview for the full picture.