When an AI agent works on a TYPO3 project, it mostly needs to answer three questions again and again: is the Composer setup still valid, does static analysis complain, and does the site still render? The easy way is to let the agent run shell commands. The problem with the easy way is that a shell can do everything else too.<\/p>\n
The Model Context Protocol (MCP) gives you another option: you write a small server that offers a few tools<\/em> with typed inputs, and the agent can call exactly those. Nothing more. This post builds such a server with the official TypeScript SDK, with three read-only tools for a DDEV-based PHP project.<\/p>\n With a shell, every permission decision is about a string. Is With an MCP tool, the decision is about a function you wrote. The The MCP quickstart currently uses the package In A few details that matter:<\/p>\n PHPStan has to be installed in the project ( Test the server before any AI gets near it. The MCP Inspector has a CLI mode:<\/p>\n For Claude Code, a project-scoped server goes into Claude Code asks for approval before it uses a project-scoped server in an interactive session, which is right: a cloned repository should not start processes on your machine silently. After approval the tools appear as An allow rule with a wildcard is only accepted after the literal Be honest about the boundary. The MCP server runs as your user, outside Claude Code’s Bash sandbox, so its own code must be trustworthy. And if the agent still has an unrestricted Bash tool next to it, the MCP server is a convenience, not a security measure. The value comes when you combine it with permissions: allow the three MCP tools, keep Bash on “ask” or deny the commands they replace. Then the routine checks run without interruptions, and every prompt you see is about something new.<\/p>\n If this post helped you, I will be really happy. Cheers!<\/p>\n Instead of giving an agent a shell, give it three safe tools. A small MCP server in TypeScript that runs composer validate, PHPStan and a frontend smoke check, registered in .mcp.json.<\/p>\n","protected":false},"author":1,"featured_media":107,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[18],"tags":[34,37,44,43],"class_list":["post-106","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai-engineering","tag-ai-agents","tag-automation","tag-mcp","tag-security"],"yoast_head":"\nWhy read-only tools are easier to trust<\/h2>\n
ddev exec composer validate<\/code> safe? Yes. Is ddev exec composer validate && rm -rf var\/<\/code> safe? Claude Code splits compound commands and checks each part, but you still review strings, and strings have many shapes.<\/p>\nphpstan<\/code> tool below accepts a path from a fixed list and a level from 0 to 10. There is no way to pass it a second command, because the command is assembled inside the server with execFile<\/code>, without a shell in between. You review the code once, and every call afterwards is boring. Boring is what I want from an agent’s tools.<\/p>\nStep 1: set up the project<\/h2>\n
@modelcontextprotocol\/server<\/code> together with zod<\/code> for input schemas, and Node.js 20 or newer. I put the server into tools\/project-checks\/<\/code> of the project:<\/p>\nmkdir -p tools\/project-checks\/src && cd tools\/project-checks\nnpm init -y\nnpm install @modelcontextprotocol\/server zod\nnpm install -D @types\/node typescript<\/code><\/pre>\npackage.json<\/code> set \"type\": \"module\"<\/code> and a \"build\": \"tsc\"<\/code> script. The tsconfig.json<\/code> from the quickstart works as is (module<\/code> and moduleResolution<\/code> set to Node16<\/code>, outDir<\/code> .\/build<\/code>, rootDir<\/code> .\/src<\/code>).<\/p>\nStep 2: the server<\/h2>\n
import { execFile } from \"node:child_process\";\nimport { promisify } from \"node:util\";\nimport { McpServer } from \"@modelcontextprotocol\/server\";\nimport { serveStdio } from \"@modelcontextprotocol\/server\/stdio\";\nimport { z } from \"zod\";\n\nconst run = promisify(execFile);\nconst PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();\nconst BASE_URL = new URL(process.env.BASE_URL ?? \"https:\/\/myport.ddev.site\");\n\n\/\/ Runs a command inside the DDEV web container. No shell is involved.\nasync function ddev(args: string[], timeout = 120_000): Promise<string> {\n try {\n const { stdout, stderr } = await run(\"ddev\", [\"exec\", ...args], {\n cwd: PROJECT_DIR,\n timeout,\n maxBuffer: 2 * 1024 * 1024,\n });\n return (stdout + stderr).trim() || \"(no output)\";\n } catch (error: any) {\n \/\/ A non-zero exit code is a result, not a crash: report the output\n return `exit ${error.code ?? \"?\"}n${(error.stdout ?? \"\") + (error.stderr ?? \"\")}`.trim();\n }\n}\n\nconst text = (t: string) => ({ content: [{ type: \"text\" as const, text: t }] });\nconst readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };\n\nfunction createServer() {\n const server = new McpServer({ name: \"project-checks\", version: \"0.1.0\" });\n\n server.registerTool(\n \"composer_validate\",\n {\n description: \"Run composer validate --strict in the project. Changes nothing.\",\n inputSchema: z.object({}),\n annotations: readOnly,\n },\n async () => text(await ddev([\"composer\", \"validate\", \"--strict\", \"--no-check-publish\"])),\n );\n\n server.registerTool(\n \"phpstan\",\n {\n description: \"Run PHPStan on one of the allowed paths and return the raw report.\",\n inputSchema: z.object({\n path: z.enum([\"Source\/Extension\", \"packages\"]).describe(\"Directory to analyse\"),\n level: z.number().int().min(0).max(10).default(5),\n }),\n annotations: readOnly,\n },\n async ({ path, level }) =>\n text(await ddev([\n \"vendor\/bin\/phpstan\", \"analyse\", path,\n `--level=${level}`, \"--no-progress\", \"--error-format=raw\",\n ], 300_000)),\n );\n\n server.registerTool(\n \"smoke_check\",\n {\n description: \"Request one page of the local site; report HTTP status, size and error markers.\",\n inputSchema: z.object({\n path: z.string().regex(\/^\/(?!\/)[A-Za-z0-9\/_.-]*$\/).default(\"\/\").describe(\"Path, e.g. \/blog\/\"),\n }),\n annotations: readOnly,\n },\n async ({ path }) => {\n const url = new URL(path, BASE_URL);\n if (url.origin !== BASE_URL.origin) {\n return text(`Refused: ${url} is not on ${BASE_URL.origin}`);\n }\n const response = await fetch(url, { redirect: \"manual\" });\n const body = await response.text();\n const markers = [\"Oops, an error occurred\", \"Fatal error\", \"Uncaught\", \"There has been a critical error\"]\n .filter((marker) => body.includes(marker));\n return text(`${url} -> ${response.status}, ${body.length} bytes, markers: ${markers.join(\", \") || \"none\"}`);\n },\n );\n\n return server;\n}\n\nserveStdio(createServer, {\n onerror: (error) => console.error(\"project-checks error:\", error),\n});\nconsole.error(\"project-checks running on stdio\");<\/code><\/pre>\n\n
console.log()<\/code>.<\/strong> A stdio server talks JSON-RPC over stdout. One stray log line there breaks the protocol. Log to stderr with console.error()<\/code>.<\/li>\nserveStdio<\/code> takes a factory.<\/strong> The current SDK calls createServer()<\/code> whenever it needs an instance, so the function must return a new McpServer<\/code> each time. The older server.connect(new StdioServerTransport())<\/code> wiring still compiles, but according to the quickstart it only serves clients that use the older handshake.<\/li>\nreadOnlyHint: true<\/code> tells the client what the tool does; it enforces nothing. What makes the tool read-only is its code: fixed binaries, fixed arguments, an enum for paths.<\/li>\nsmoke_check<\/code> that accepts any path starting with a slash. A path like \/\/example.com<\/code> is a protocol-relative URL, and new URL()<\/code> happily resolves it to another host. The regex above rejects a second slash at the start, and the origin check catches anything I did not think of.<\/li>\n<\/ul>\ncomposer require --dev phpstan\/phpstan<\/code>), otherwise the tool just reports the missing binary. hoja.in itself has no PHPStan yet; the tool is generic.<\/p>\nStep 3: build and test without an agent<\/h2>\n
npm run build\nnpx @modelcontextprotocol\/inspector --cli node build\/index.js --protocol-era modern --method tools\/list\nnpx @modelcontextprotocol\/inspector --cli node build\/index.js \n --method tools\/call --tool-name smoke_check --tool-arg path=\/blog\/<\/code><\/pre>\ntools\/list<\/code> returns the three tools with their JSON schemas: the enum for path<\/code>, minimum and maximum for level<\/code>, and the annotations. That is what the model sees, so read it once with the eyes of somebody who does not know your project.<\/p>\nStep 4: register it in .mcp.json<\/h2>\n
.mcp.json<\/code> at the project root, which you commit. Environment variables can be expanded with ${VAR}<\/code> or ${VAR:-default}<\/code>. The relative path and the process.cwd()<\/code> fallback assume the server is started from the project root; if your setup starts it elsewhere, set PROJECT_DIR<\/code> and use an absolute path:<\/p>\n{\n \"mcpServers\": {\n \"project-checks\": {\n \"command\": \"node\",\n \"args\": [\"tools\/project-checks\/build\/index.js\"],\n \"env\": {\n \"BASE_URL\": \"${PROJECT_BASE_URL:-https:\/\/myport.ddev.site}\"\n }\n }\n }\n}<\/code><\/pre>\nmcp__project-checks__composer_validate<\/code> and so on. Allow them without prompts in .claude\/settings.json<\/code>:<\/p>\n{\n \"permissions\": {\n \"allow\": [\"mcp__project-checks__*\"]\n }\n}<\/code><\/pre>\nmcp__<server>__<\/code> prefix, so you cannot accidentally allow every MCP tool of every server this way.<\/p>\nWhat this does not protect<\/h2>\n
Further reading<\/h2>\n
\n