Installing the server

Standalone#

Clone the repository and install its dependencies once:

git clone https://github.com/TYPO3/dev-companion.git typo3-dev-companion
cd typo3-dev-companion
composer install

The clone takes its name from the binary rather than from the repository. So the absolute path in every command below is the directory git clone just made.

Then change into the project the agent works in and install the entrypoint into its .mcp.json:

cd /path/to/your/project
/absolute/path/to/typo3-dev-companion/bin/typo3-dev-companion install

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.

ln -s /absolute/path/to/typo3-dev-companion/bin/typo3-dev-companion ~/.local/bin/

claude mcp add --scope user typo3-dev-companion -- typo3-dev-companion

As a dependency#

The package is on Packagist as typo3/dev-companion, so the project that uses it requires it and nothing else:

composer require "typo3/dev-companion:@dev"

The constraint names a stability because no release has a tag. dev-main is the only version there is, and the default minimum stability refuses a plain require. The experimental note in the readme is why — pin a commit where the project depends on it.

That is the way in where the entry has to be shareable. A DDEV project, or a team where each checkout should carry the same one. The entry then names a path inside the project. Composer exposes the stdio entrypoint as vendor/bin/typo3-dev-companion. Install it from that project's root:

vendor/bin/typo3-dev-companion install

vendor/bin/typo3-dev-companion help lists both commands and every client they accept. 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 looks exactly like a hang.

The entry names the entrypoint inside the project where the client can resolve that, and this server's absolute path everywhere else:

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

Which clients resolve a path inside the project, and why the others get an absolute one, is Which path the entry names. The knowledge base ships inside the package, so nothing else needs a deployment or a configuration.

To work against a checkout instead, clone it and name it as a path repository. That changes the server and the project that uses it in one go. Composer symlinks that into vendor/ so an edit is live in the project:

git clone https://github.com/TYPO3/dev-companion.git typo3-dev-companion

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

The require is the same one and resolves against the checkout instead.

ddev exec vendor/bin/typo3-dev-companion install

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

Naming the client#

No client name 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 configuration for it. --agent= names a client that reads elsewhere. Each one receives the skills at its native project path and, where it supports one, its native MCP configuration. --agent= does not take generic, because it is nobody's name.

Antigravity and Pi receive skills only, so for them there is no entry and nothing to finish. typo3-dev-companion help prints the same identifiers.

"chat.useAgentSkills": true

Finishing in the client#

The entry on disk registers the server with nothing. A client that scopes project servers behind an approval has not seen the question yet. A session that was already open when the file landed runs against the configuration it started with. Both end with an entry that is entirely correct, a published skill that names the tools beside it, and no tool in the session. That is where two sessions in one project went, on 2026-07-29 and 2026-07-31.

install and update print what follows under the line that reports the entry, so you read it at the terminal rather than here. What each client needs is the client's own property, so each line below is that client's own documentation, read on 2026-08-02. A client whose documentation does not answer stays open rather than gets a fill:

• Claude Code — a restart and an approval. "Claude Code reads .mcp.json at session start. Exit and restart the session after editing the file", and "the first time Claude Code sees a project-scoped server, it asks you to approve it". Approve at the prompt or in /mcp; a server once refused is reset with claude mcp reset-project-choices. (quickstart, reference)
• Amp — an approval. "MCP servers in workspace settings (.amp/settings.json) require explicit approval before they can run." And "in the CLI, you'll be prompted to approve workspace servers when they're first detected". amp mcp approve typo3-dev-companion does it without the prompt, and amp mcp doctor shows one awaiting approval. (manual)
• VS Code — a trust confirmation. "When you add an MCP server to your workspace or change its configuration, you need to confirm that you trust the server and its capabilities before starting it." The experimental chat.mcp.autoStart restarts the server when the configuration changes. (MCP servers)
• Codex — a trusted project. Codex scopes MCP servers "to a project with .codex/config.toml (trusted projects only)", so the trust prompt for the directory is what admits them. Whether a live session reads the file again has no documentation; codex mcp list reports what it has. (MCP)
• Zed — a trusted worktree. The MCP page describes context_servers only in the file opened with zed: open settings file. But the rest of the documentation puts it in the project file, "every worktree opened may contain a .zed/settings.json file with extra configuration options that may require installing and spawning language servers or MCP servers". Zed's own advisory for the vulnerability the trust model answers agrees. It says "the Zed IDE loads Model Context Protocol (MCP) configurations from the settings.json file located within a project's .zed subdirectory". So the client reads the written entry, behind a gate the other clients do not have. Every worktree starts in Restricted Mode. That prevents "project settings (.zed/settings.json) from being parsed and applied" and "MCP servers from being installed and spawned". The title bar carries an exclamation mark until the user trusts the directory there or with workspace::ToggleWorktreeSecurity. Whether a window that was already open reads a new file has no documentation. Read 2026-08-02, when the current release was v1.13.1; the trust model arrived in v0.218.2-pre. (MCP, trusted worktrees, GHSA-cv6g-cmxc-vw8j)
• Kiro — nothing. "Changes to MCP configuration apply automatically when you save the file" and "servers will reconnect". A tool autoApprove does not name is still asked about on the call. (MCP configuration)
• Droid — nothing. "Droid reloads automatically when an mcp.json file changes, so new servers are available immediately." Each tool gets its approval on first use, and droid mcp permissions keeps that approval. (MCP)
• Junie — no approval: servers "imported from the mcp.json file are enabled by default". Whether an IDE that was already open reads a new one is not documented; the list is Settings | Tools | Junie | MCP Settings. (MCP configuration)
• Cursor — unestablished. Servers stand under Customize, where a toggle switches one off, and "Cursor asks for approval before using MCP tools by default". That is the tool call, not the server. Whether a window that was already open reads a new file is not documented. (MCP)
• opencode — unestablished. enabled: false switches a server off, which the written entry does not. Whether a session that was already open reads the file again has no documentation. (MCP servers)
• Grok — unestablished. A project .grok/config.toml does contribute [mcp_servers], up to the git root. Whether a session that runs reads it again, and whether anything gates it, has no documentation. grok mcp doctor reports what it has. (MCP servers)

Where a session has the entry and still offers no typo3_ tool, Checking that it answers is the rest of the ladder.

Keeping it current#

A published skill is a copy, so it goes stale the moment this package moves. update is what refreshes it, along with the client entry:

vendor/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.

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 its first install needs a different entry than the one that is there. So does one that gained a DDEV configuration since. update is what moves it. An entry that starts something other than this server is somebody else's and gets a refusal 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 where the entry carries the variables below. 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 that continues on the next line gets a refusal with the line number rather than a rewrite around it. A kept line means a known end of it.

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

What the entry may carry#

Four environment variables, all set in the env block of the client entry, which is the one part of it install and update leave alone:

• TYPO3_DEV_COMPANION_ROOT — the installation to read, where the one found from the working directory is the wrong one — Checking that it answers.
• TYPO3_DEV_COMPANION_CONSOLE — the command that runs that installation's console, such as ddev exec .build/bin/typo3 — Checking that it answers.
• TYPO3_DEV_COMPANION_EXCLUDE_TOOLS — tool names, comma-separated, the client does not get, see which tools the client gets.
• TYPO3_DEV_COMPANION_SKILL_REFRESH — off reports stale skills instead of a repair — when they go stale.

Removing it#

Four things landed in the project, and no command takes them out again, so to remove the server is to delete them by hand:

• the typo3-dev-companion entry in the client file the table under naming the client names, and only that entry. The file may carry other servers;
• one directory per published skill in the skills directory the table names;
• the block between the two marks in the instruction file the table names, The instruction block;
• .typo3-dev-companion/, where the record sits.

Neither command touches the project's .gitignore. Every directory this package writes, each published skill, and .typo3-dev-companion/, carries a .gitignore of its own that says *. That 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. No ignore rule covers merged agent or MCP configuration such as .codex/config.toml or .mcp.json, because the project may share it.

Development builds before this wrote a typo3-dev-companion.json at the project root. They wrote a block between # BEGIN typo3-dev-companion and # END typo3-dev-companion into the project's .gitignore. Nothing here reads or removes either. A project that has them got its setup by hand and takes them out the same way, and the next install records the clients again.

Which path the entry names#

Three shapes, and which one a client gets is a property of that client. Where the project has this server as a Composer dependency, or is its checkout, the entry names the path inside the project. That goes through ddev exec where there is a DDEV configuration, and through ${workspaceFolder} in VS Code and Cursor. Everywhere else it is this server's absolute path on the machine the install ran on. That is a value one machine is right about, in a file its own client documents as the shared, committed one. There the install says so; the read below is why there is nothing better to write.

A relative path would have to resolve against the working directory the client launches the process in. The MCP specification does not define one: the stdio transport is "the client launches the MCP server as a subprocess" and nothing about a directory. So it is each client's property, read on 2026-08-09 from the same pages as Finishing in the client.

One client documents the workspace as the default, and three offer a cwd to set. Two resolve a variable that names the project root, and one refuses expansion in those fields outright. Claude Code is the sharpest of them. It sets CLAUDE_PROJECT_DIR in the spawned server's environment "so your server can resolve project-relative paths without depending on the working directory". The same variable in a project-scoped .mcp.json "requires a default such as ${CLAUDE_PROJECT_DIR:-.}", which is the work directory again.

The variable is what the two who have one get, rather than the plain relative path VS Code's default working directory would also carry. It says the same thing without a rest on where the process started. That is the property the client most sessions use asks for by name:

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

For the other nine a relative entry would be wrong on the machine that wrote it too. An absolute one is at least right there. So the install says it, per client and at the terminal, beside the line that reports the entry — D-DIS-016.

None of this reaches a standalone checkout. ${workspaceFolder} names a path inside the project, and a server that runs from somewhere else has none. There the absolute path is the only one that exists, whatever the client resolves.

The sources are the same as finishing in the client, plus three more. The MCP transports specification, VS Code's configuration reference and Cursor's MCP page.