Installing the server

Standalone#

Clone the repository and install the dependencies once:

composer install

Then install the entrypoint into the current project's .mcp.json:

/absolute/path/to/typo3-dev-companion/bin/typo3-dev-companion install

For Codex, install its project configuration and task skills directly:

/absolute/path/to/typo3-dev-companion/bin/typo3-dev-companion install --agent=codex

Refresh them after updating this package:

/absolute/path/to/typo3-dev-companion/bin/typo3-dev-companion update

update takes --agent=<client> as well, but rarely needs to: install records every client it set up in .typo3-dev-companion/state.json, and without an agent update refreshes all of them. A project is usually worked on by more than one, and which ones is knowledge only the project has.

When they go stale#

A published skill is a copy, so it goes stale without saying so: the client loads the file it finds, the workflow reads as current whatever version wrote it, and a tool name that has been renamed since fails at the call rather than at the load. The record therefore carries a digest of what was published, and a server started in that project compares it before the first call — R-DIS-025.

Where they no longer match, the server says so twice. The long line goes to stderr, naming what differs and the command that fixes it, for whoever is at a terminal. One short sentence goes into the instructions a client is handed at initialize, for the agent that is about to load a skill; it is short because that statement is budgeted and the exclusion prefix competes for the same room.

Three things make it speak: a skills directory that no longer holds what was published there, a digest that no longer matches, and a record written before the digest existed. The first is the one to expect — every published directory ignores itself, which is also what git clean -xdf takes with it. A project this package never installed into is silent.

Where the record carries drafts, the line says update --drafts: a run that does not ask for them removes them, and somebody acting on the line wants the project they have.

Refreshing on update#

The copy goes stale the moment this package moves, so a project can have the thing that moved it run the refresh. Composer fires post-update-cmd after composer update, and the project's own composer.json is where that is wired:

{
    "scripts": {
        "post-update-cmd": [
            "typo3-dev-companion update"
        ]
    }
}

Nothing here writes that line. install and update write client configuration, the skills and the record, and a file that decides what the project consists of is not among them.

The command needs no path: Composer pushes the project's declared bin-dir onto PATH before running a script, so the bare name resolves whether the project puts its binaries in vendor/bin or in .build/bin. It runs in the project root, which is where the record is.

A project where nothing is installed is told so and the run succeeds. That is the ordinary case for everybody but the person who set it up: the record sits below a directory that ignores itself, so it is in no checkout but theirs, and a script that exits non-zero fails the whole Composer run.

What the hook does not cover is the fresh clone: post-update-cmd fires on composer update and on an install with no lock file, so a colleague installing from the lock runs nothing. There the notice at the next server start is what says the copies are behind.

Add --drafts to that line where the project has drafts published in it. A run that does not ask for them takes them out, and with the hook in place that happens on every composer update rather than when somebody typed the command.

Trying a draft#

Both commands take --drafts, which publishes the skills that still declare themselves drafts beside the ones this server publishes:

/absolute/path/to/typo3-dev-companion/bin/typo3-dev-companion install --agent=claude --drafts

What it is for is the review step Writing a task skill makes a condition of publishing. Reading a draft in this repository is not reading it where it loads, and the questions it exists to raise — is this the order the work actually goes in, is the step that decides the outcome in it — are raised by using it on a real task.

The drafts are recorded under their own key in .typo3-dev-companion/state.json, because what is in a project unreviewed is the question somebody opens that file to answer. They are the one thing an update does not carry over: a run that does not ask for them removes them again and says so. Sticky would be the convenient reading and the wrong one — an unreviewed workflow that stays in a project because somebody once tried it is what publishing being a deliberate edit exists to prevent.

Both commands write the client entry, because what belongs in it is a property of the project rather than of the run: a project that required this package after it was first installed, or that gained a DDEV configuration since, needs a different entry than the one that is there, and update is what moves it. An entry that starts something other than this server is somebody else's and is refused instead — the two commands then say so and change nothing.

They own the command in that entry and nothing else. Whatever the caller put beside it stays — env above all, which is the only place a client configuration carries TYPO3_DEV_COMPANION_EXCLUDE_TOOLS. In a .codex/config.toml or a .grok/config.toml that means every line of the section this package does not write, so a value continued on the next line is refused with the line number rather than rewritten around: keeping a line means knowing where it ends.

Naming no client at all is a setup of its own, recorded as generic: install then writes the .mcp.json entry and publishes the skills to .agents/skills, the two locations a client finds without being configured for it. It is refreshed by the same update as every named client. --agent= does not take generic, because it is nobody's name.

Neither command touches the project's .gitignore. Every directory this package writes — each published skill, and .typo3-dev-companion/ where the record sits — carries a .gitignore of its own that says *, which covers the directory and that file with it: git reports nothing there, and a skill the project wrote itself, in the same skills directory, stays visible. Merged agent or MCP configuration such as .codex/config.toml or .mcp.json is ignored nowhere, because the project may share it.

Development builds before this wrote a typo3-dev-companion.json at the project root and a block between # BEGIN typo3-dev-companion and # END typo3-dev-companion into the project's .gitignore. Neither is read or removed by anything here — the package is unreleased, so a project that has them was set up by hand and takes them out the same way, and the next install records the clients again.

It writes the following shape with the actual absolute path:

{
  "mcpServers": {
    "typo3-dev-companion": {
      "type": "stdio",
      "command": "php",
      "args": ["/absolute/path/to/typo3-dev-companion/bin/typo3-dev-companion"]
    }
  }
}

This is the setup to use when working on the knowledge base itself, since the feedback/ tools only exist in a checkout.

As a dependency#

The package is not published on Packagist, so it is required from a local checkout (or a Git URL) through a repositories entry in the consuming project's composer.json:

{
  "repositories": [
    { "type": "path", "url": "/absolute/path/to/typo3-dev-companion" }
  ]
}

composer require typo3/dev-companion

Composer then exposes the stdio entrypoint as vendor/bin/typo3-dev-companion. Install it from the consuming project's root:

vendor/bin/typo3-dev-companion install

Use vendor/bin/typo3-dev-companion install --agent=codex for the corresponding Codex setup, and vendor/bin/typo3-dev-companion update to refresh it and every other client installed there.

vendor/bin/typo3-dev-companion help lists both commands and every client they accept. Passing anything else fails with that same text: without an argument the entrypoint is the MCP transport itself and waits on stdin, which at a terminal is indistinguishable from a hang.

The same commands support the agent identifiers amp, junie, cursor, claude, copilot, factory, kiro, opencode, antigravity, zed, pi, and grok. Each receives the skill at its native project path and, where the client supports it, its native MCP configuration. Antigravity and Pi receive skills only.

"chat.useAgentSkills": true

{
  "servers": {
    "typo3-dev-companion": {
      "type": "stdio",
      "command": "php",
      "args": ["${workspaceFolder}/vendor/bin/typo3-dev-companion"]
    }
  }
}

In a DDEV project#

Run the installer inside DDEV:

ddev exec vendor/bin/typo3-dev-companion install --agent=codex

The project directory is mounted, so the skills are available to the host at .agents/skills. The generated MCP entry deliberately starts the server with the project's container PHP, at the config.bin-dir the project declares — .build/bin/typo3-dev-companion in the layout most extension repositories use:

{
  "mcpServers": {
    "typo3-dev-companion": {
      "type": "stdio",
      "command": "ddev",
      "args": ["exec", "php", "vendor/bin/typo3-dev-companion"]
    }
  }
}

Outside DDEV — and in a DDEV project that never required the package, where the container would not see the checkout the server runs from — the generated configuration uses the absolute entrypoint, unless the client is one of the two that resolve ${workspaceFolder}:

{
  "mcpServers": {
    "typo3-dev-companion": {
      "type": "stdio",
      "command": "php",
      "args": ["/absolute/path/to/project/vendor/bin/typo3-dev-companion"]
    }
  }
}

The knowledge base ships inside the package, so nothing else needs to be deployed or configured.

Which tools are offered#

Every one of them, wherever the server was started. Some of what it knows is the core's own contribution process — the review rules, the Gerrit workflow, the core testing suites — and none of that transfers to a project. What it is worth is said in the answer, per topic and per path, because whether a task is core work is a property of the task and not of the directory it is asked from.

The server used to leave those three tools out of a Composer project. That read the repository where the task was meant, and a core patch written from a site installation was answered as core work and then sent to a tool the client had not been given.

• TYPO3_DEV_COMPANION_EXCLUDE_TOOLS removes tools by their comma-separated names, and is the only thing that shortens the list. Three names never shorten it: typo3_server_scope, because it is what explains a shorter list, and typo3_feedback_record and typo3_feedback_list, because the feedback channel is a development tool for building this server rather than part of using it — R-SCO-009.
• A name in it that takes no tool away is reported rather than absorbed, on stderr before the transport starts and again under excludedTools.ignored in typo3_server_scope. That covers both reasons a name takes nothing away: no tool of this server answers to it — a rename, or a typo — or it is one of the three above.

typo3_server_scope names what was really excluded, and nothing routes to a tool that is not there. What the server says is gone is what is gone: a name that changed nothing is never reported as a missing capability, because a client cannot check the claim and pays for it out of the instructions it is sent.

What comes with it#

Clients that expose MCP prompts also list commit_message. It turns a summary into the same checked draft as typo3_commit_message_guide; the rules remain in the guide rather than being duplicated in the prompt.

Task skills are authored once below skills/. They contain routing and order, not a second copy of tool answers; client installation publishes them from that source.