From f00da3405e0f3c3574bd4f4fb08a01211481a1e3 Mon Sep 17 00:00:00 2001
From: yangweijie <917647288@qq.com>
Date: Sat, 17 Oct 2026 14:34:08 +0800
Subject: [PATCH 1/2] feat(tools): add a selfbuild mcp tool

---
 .gitignore                                |   1 +
 phpunit.xml                               |   3 +
 tests/windows/clang/README.md             |   2 +-
 tools/typephp-mcp/.gitignore              |   1 +
 tools/typephp-mcp/README.md               | 133 +++++
 tools/typephp-mcp/build.bat               |  57 +++
 tools/typephp-mcp/main.php                |  80 +++
 tools/typephp-mcp/project.yml             |  18 +
 tools/typephp-mcp/src/CodeIndex.php       | 594 ++++++++++++++++++++++
 tools/typephp-mcp/src/CompilerOracle.php  | 208 ++++++++
 tools/typephp-mcp/src/Config.php          |  10 +
 tools/typephp-mcp/src/DocIndex.php        | 294 +++++++++++
 tools/typephp-mcp/src/IndexInfo.php       |  90 ++++
 tools/typephp-mcp/src/McpServer.php       | 435 ++++++++++++++++
 tools/typephp-mcp/src/ProjectDetector.php |  72 +++
 tools/typephp-mcp/src/RepoRoot.php        | 109 ++++
 tools/typephp-mcp/src/Restrictions.php    | 167 ++++++
 tools/typephp-mcp/src/TextUtil.php        |  77 +++
 tools/typephp-mcp/src/ToolDefinitions.php | 177 +++++++
 tools/typephp-mcp/tests/McpBinaryTest.php | 117 +++++
 tools/typephp-mcp/tests/McpServerTest.php | 592 +++++++++++++++++++++
 21 files changed, 3236 insertions(+), 1 deletion(-)
 create mode 100644 tools/typephp-mcp/.gitignore
 create mode 100644 tools/typephp-mcp/README.md
 create mode 100644 tools/typephp-mcp/build.bat
 create mode 100644 tools/typephp-mcp/main.php
 create mode 100644 tools/typephp-mcp/project.yml
 create mode 100644 tools/typephp-mcp/src/CodeIndex.php
 create mode 100644 tools/typephp-mcp/src/CompilerOracle.php
 create mode 100644 tools/typephp-mcp/src/Config.php
 create mode 100644 tools/typephp-mcp/src/DocIndex.php
 create mode 100644 tools/typephp-mcp/src/IndexInfo.php
 create mode 100644 tools/typephp-mcp/src/McpServer.php
 create mode 100644 tools/typephp-mcp/src/ProjectDetector.php
 create mode 100644 tools/typephp-mcp/src/RepoRoot.php
 create mode 100644 tools/typephp-mcp/src/Restrictions.php
 create mode 100644 tools/typephp-mcp/src/TextUtil.php
 create mode 100644 tools/typephp-mcp/src/ToolDefinitions.php
 create mode 100644 tools/typephp-mcp/tests/McpBinaryTest.php
 create mode 100644 tools/typephp-mcp/tests/McpServerTest.php

diff --git a/.gitignore b/.gitignore
index ad53f406..472f0c33 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,3 +36,4 @@ tests/**/*.sh
 /tests/wasm/harness/node_modules/
 /ide-helper/
 /debug/
+/tools/typephp-mcp/build/
diff --git a/phpunit.xml b/phpunit.xml
index 76b70f89..9dd280ca 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -4,5 +4,8 @@
     <testsuite name="Tests">
       <directory suffix="Test.php">./phpunit</directory>
     </testsuite>
+    <testsuite name="TypePhpMcpTests">
+      <directory suffix="Test.php">./tools/typephp-mcp/tests</directory>
+    </testsuite>
   </testsuites>
 </phpunit>
diff --git a/tests/windows/clang/README.md b/tests/windows/clang/README.md
index d7018550..46647c5a 100644
--- a/tests/windows/clang/README.md
+++ b/tests/windows/clang/README.md
@@ -16,7 +16,7 @@ session in the compiler repository:
 ```powershell
 . .\tests\windows\clang\set-llvm-env.ps1 `
   -LlvmHome D:\workspace\tools\llvm-23.1.2 `
-  -VcToolsRoot 'C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207' `
+  -VcToolsRoot 'D:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207' `
   -WindowsSdkRoot 'C:\Program Files (x86)\Windows Kits\10' `
   -WindowsSdkVersion 10.0.26100.0
 
diff --git a/tools/typephp-mcp/.gitignore b/tools/typephp-mcp/.gitignore
new file mode 100644
index 00000000..a5b7451f
--- /dev/null
+++ b/tools/typephp-mcp/.gitignore
@@ -0,0 +1 @@
+/build.log
diff --git a/tools/typephp-mcp/README.md b/tools/typephp-mcp/README.md
new file mode 100644
index 00000000..95951243
--- /dev/null
+++ b/tools/typephp-mcp/README.md
@@ -0,0 +1,133 @@
+# typephp-mcp — TypePHP 辅助开发 MCP Server（TypePHP 自己实现）
+
+用 TypePHP AOT 编译器把 PHP 源码编译成原生二进制的 MCP（Model Context Protocol）server，
+通过 stdio 以换行分隔的 JSON-RPC 2.0 对外提供服务。它替代了设计文档
+（《TypePHP辅助开发MCP设计.md》）中原计划的 Python/FastMCP 实现：**协议层、检索层、
+编译器 oracle 全部由 TypePHP 编译后的 PHP 代码完成**，运行时只依赖 PHP 运行时 DLL。
+
+## 工具面（12 个）
+
+| 工具 | 作用 |
+|---|---|
+| `check_code` | 第一工具。跑 `php bin/tpc.php --dry` 验证 TypePHP 子集合法性，返回 `file:line` 诊断或 OK（只覆盖 C++ 生成，不覆盖链接期） |
+| `list_restrictions` | 写码前必读。TypePHP 裁剪规则（程序结构/类型/引用/对象/控制流/std 表面/stub 契约/构建配置），可按 topic 查询 |
+| `get_symbol` | 按精确名字查函数/类/接口/trait/enum/const 声明，返回签名 + `file:line`（扫 src/、examples/、tests/std/） |
+| `list_stdlib` | 列出 tests/std 各分类及测试标题；指定分类返回该分类全部用例 |
+| `get_example` | 返回 examples/ 下可运行示例（单文件内容，或目录的文件清单 + README/main.php/project.yml 摘录） |
+| `get_stub_api` | 解析 `.stub.php` ABI 契约：列出全部 stub 文件，或读取指定文件的声明 |
+| `search_docs` | docs/zh-cn + docs/en 全文检索，返回带 `docs/<lang>/<file>.md#<heading> (L<line>)` 出处的 chunk |
+| `search_code` | grep examples/、tests/std/、src/，返回 `file:line` + 所在声明 |
+| `get_changelog` | 读 CHANGELOG.md：最新小节或指定版本 |
+| `get_build_config_help` | project.yml 字段、bin/lib/ext 三种模式、CLI 选项、stub 契约 |
+| `list_topics` | 列出全部文档标题（双语） |
+| `get_index_info` | 元数据：repo 根、tpc 版本、git commit、文档数、工具清单（staleness 自证） |
+
+设计取舍：
+
+- **无预建索引**。docs/examples/src 每次实时读取（约 2 MB），从结构上消除索引过期；
+  `get_index_info` 用 tpc 版本 + git commit 自证时效。
+- **约束注入**。`initialize` 的 instructions 与 `check_code`/`list_restrictions` 的
+  tool description 中内置约 800 token 的 TypePHP 红线摘要，不调工具也能压住头号失败模式。
+- **返回摘录 + 出处，不返整文件**；单次结果有字节预算（约 4 KB），UTF-8 边界安全。
+
+## 构建
+
+前置：VS 2022 BuildTools（`vcvars64.bat`，经 vswhere 自动定位）与一个 tpc 包。
+
+```bat
+tools\typephp-mcp\build.bat
+```
+
+脚本所有路径都相对自身位置解析，**可从任意工作目录执行**：
+
+| 路径 | 解析方式 |
+|---|---|
+| `project.yml` / `build/` / 输出 exe | 脚本所在目录 |
+| `bin\tpc.php` | 脚本目录上两级（仓库根） |
+| tpc 包（phpx/PHP SDK/运行时 DLL） | 脚本目录上三级 + `tpc_v0.9.5_windows_x64`（即仓库同级目录） |
+
+换 tpc 版本只需改 `build.bat` 里 `TPC_PACKAGE` 一行中的版本目录名；若 tpc 包不在
+默认位置，先 `set PHP_HOME=<包目录>` 再运行（脚本找不到包时会给出该提示并以退出码 1 失败）。
+
+产物 `typephp_mcp.exe` 及运行时 DLL（phpx/php8ts/gmp/mpfr/mpdec）都在本目录，
+**不需要改 PATH**。
+
+## 运行 / 接入 MCP 客户端
+
+```bat
+set TYPEPHP_MCP_ROOT=D:\git\php\aot-compiler
+tools\typephp-mcp\typephp_mcp.exe
+```
+
+环境变量：
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `TYPEPHP_MCP_ROOT` | 从 cwd 向上找 `bin/tpc.php` + `docs/`，再退到构建期默认值 | 仓库根 |
+| `TYPEPHP_MCP_PHP` | `php`（PATH 查找） | `check_code` / `get_index_info` 调编译器用的 PHP |
+
+Finch（`~/.finch/mcp/servers.json`，对象数组）：
+
+```json
+{
+  "name": "typephp-dev",
+  "enabled": true,
+  "command": "D:\\git\\php\\aot-compiler\\tools\\typephp-mcp\\typephp_mcp.exe",
+  "args": []
+}
+```
+
+Claude Code：
+
+```bash
+claude mcp add typephp-dev -- D:\git\php\aot-compiler\tools\typephp-mcp\typephp_mcp.exe
+```
+
+CodeBuddy（用户级配置 `%USERPROFILE%\.codebuddy\mcp.json`，在 MCP 标签页手动添加等价）：
+
+```json
+{
+  "mcpServers": {
+    "typephp-mcp": {
+      "type": "stdio",
+      "command": "D:/git/php/aot-compiler/tools/typephp-mcp/typephp_mcp.exe",
+      "args": [],
+      "env": {
+        "TYPEPHP_MCP_ROOT": "D:/git/php/aot-compiler",
+        "TYPEPHP_MCP_PHP": "D:/git/php/tpc_v0.9.5_windows_x64/php.exe",
+        "PHPX_HOME": "D:/git/php/tpc_v0.9.5_windows_x64/phpx",
+        "PHP_HOME": "D:/git/php/tpc_v0.9.5_windows_x64"
+      }
+    }
+  }
+}
+```
+
+注意：**路径一律用正斜杠**。CodeBuddy 的 MCP 启动器会剥掉配置里的反斜杠
+（`D:\\git\\...` 会变成 `D:git...`，报 `not recognized ... Connection closed`），
+正斜杠在 Windows 下全链路可用（与同配置中正常工作的 ripwire 条目一致）。
+
+`env` 四个变量都建议显式设置：客户端的工作目录不确定，`TYPEPHP_MCP_ROOT` 保证仓库定位；
+后三个把 `check_code` 调用的编译器钉在 tpc 包上，避免继承到过期的 `PHPX_HOME`/`PHP_HOME`
+或 PATH 里没有 php。修改配置后需重启 CodeBuddy 生效。
+
+`check_code` 会调编译器，属"副作用"工具，建议在客户端对该 server 单独授权。
+
+## 测试
+
+```bash
+php vendor/bin/phpunit tools/typephp-mcp/tests/
+```
+
+- `McpServerTest`：协议分发 + 12 个工具的逻辑单测（普通 PHP 直接跑；
+  源码刻意保持在 stock PHP 与 TypePHP 的交集内，解释执行与 AOT 编译跑同一份代码）。
+- `McpBinaryTest`：驱动编译产物跑真实 stdio 会话，含逐条 flush 超时校验
+  （未构建时自动 skip）。
+
+## 已知问题（编译器侧，非本项目 bug）
+
+`STDIN/STDOUT/STDERR` 常量在某些项目形态下被 -O2 优化器折叠为字面量 `0`
+（见 `src/Translator.php::loadInternalConstants()` 与
+`src/Parser/ConstantExpressionTrait.php::parseConstFetch()` 的常量折叠路径），
+运行时 `fwrite()/fgets()` 会抛 `TypeError`。规避：`main.php` 统一用
+`fopen('php://stdin'/'php://stdout'/'php://stderr')` 打开标准流。
diff --git a/tools/typephp-mcp/build.bat b/tools/typephp-mcp/build.bat
new file mode 100644
index 00000000..aea7f3d9
--- /dev/null
+++ b/tools/typephp-mcp/build.bat
@@ -0,0 +1,57 @@
+@echo off
+REM Build typephp-mcp.exe with TypePHP (AOT).
+REM
+REM All paths are resolved relative to this script's location:
+REM   <script dir>                     project.yml, build/, output exe + DLLs
+REM   <script dir>\..\..               repo root (bin\tpc.php)
+REM   <script dir>\..\..\..\tpc_v...   tpc package (default, sibling of the repo)
+REM
+REM Prerequisites: a tpc package (see TPC_PACKAGE below) and the MSVC
+REM toolchain (located via vswhere, with a VS 2022 BuildTools fallback).
+REM If the default package location does not exist, set PHP_HOME to your
+REM tpc package directory before running this script.
+setlocal
+
+cd /d "%~dp0"
+set SCRIPT_DIR=%CD%
+
+REM --- tpc package: repo-relative default, PHP_HOME fallback ----------------
+set TPC_PACKAGE=%SCRIPT_DIR%\..\..\..\tpc_v0.9.5_windows_x64
+for %%I in ("%TPC_PACKAGE%") do set "TPC_PACKAGE=%%~fI"
+if not exist "%TPC_PACKAGE%\php.exe" (
+    if defined PHP_HOME if exist "%PHP_HOME%\php.exe" set "TPC_PACKAGE=%PHP_HOME%"
+)
+if not exist "%TPC_PACKAGE%\php.exe" (
+    echo [build] ERROR: tpc package not found at "%TPC_PACKAGE%".
+    echo [build] Fix the package path in this script, or set PHP_HOME first:
+    echo [build]     set PHP_HOME=D:\path\to\tpc_v0.9.5_windows_x64
+    exit /b 1
+)
+set "PHPX_HOME=%TPC_PACKAGE%\phpx"
+set "PHP_HOME=%TPC_PACKAGE%"
+
+REM --- repo root (bin\tpc.php lives there) -----------------------------------
+for %%I in ("%SCRIPT_DIR%\..\..") do set "REPO_ROOT=%%~fI"
+
+REM --- MSVC environment (vswhere auto-detect, VS 2022 BuildTools fallback) ---
+set "VCVARS="
+set "VSWHERE=%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere.exe"
+if exist "%VSWHERE%" (
+    for /f "usebackq tokens=*" %%I in (`"%VSWHERE%" -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath`) do set "VCVARS=%%I\VC\Auxiliary\Build\vcvars64.bat"
+)
+if not defined VCVARS set "VCVARS=D:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
+echo [build] Initializing MSVC environment: "%VCVARS%"
+call "%VCVARS%"
+if %errorlevel% neq 0 exit /b 1
+
+REM --- build -----------------------------------------------------------------
+echo [build] tpc package: "%TPC_PACKAGE%"
+"%PHP_HOME%\php.exe" "%REPO_ROOT%\bin\tpc.php" project.yml -O2 --build-dir build --no-color --no-progress
+if %errorlevel% neq 0 exit /b 1
+
+REM Deploy the PHP runtime DLLs next to the executable so it runs without
+REM touching PATH (the import libs come from the tpc package).
+for %%D in (phpx.dll php8ts.dll gmp-10.dll gmpxx-4.dll mpfr-6.dll libmpdec-4.0.1.dll libmpdec++-4.0.1.dll) do (
+    if exist "%PHP_HOME%\%%D" copy /y "%PHP_HOME%\%%D" . > nul
+)
+echo [build] Done: "%SCRIPT_DIR%\typephp_mcp.exe"
diff --git a/tools/typephp-mcp/main.php b/tools/typephp-mcp/main.php
new file mode 100644
index 00000000..dc8620f4
--- /dev/null
+++ b/tools/typephp-mcp/main.php
@@ -0,0 +1,80 @@
+<?php
+
+/**
+ * typephp-mcp entry point: newline-delimited JSON-RPC 2.0 over stdio.
+ *
+ * Wire this binary into an MCP client (Finch/Claude Code) as a stdio server.
+ * Environment:
+ *   TYPEPHP_MCP_ROOT  repository root (default: walk up from cwd, then build-time default)
+ *   TYPEPHP_MCP_PHP   php executable used by check_code/get_index_info
+ *                     (default: `php` from PATH)
+ *   TYPEPHP_MCP_PROJECT_ROOT  optional TypePHP project path(s) (separate multiple
+ *                     with ; or :) to auto-merge into the default search set when
+ *                     the client does not send MCP roots.
+ *
+ * The server also advertises the MCP roots capability and, once initialized,
+ * asks the client for its open workspace, auto-detecting any TypePHP projects
+ * (vendor/swoole/typephp, composer.json requiring it, or project.yml) and
+ * merging them into the default search set.
+ *
+ * Note: std streams are opened through php://stdin|stdout|stderr on purpose.
+ * The STDIN/STDOUT/STDERR constants are resolved at compile time and can be
+ * folded to plain integers by the optimizer in some project shapes, which
+ * breaks fwrite()/fgets() with a TypeError. Stream wrappers are always
+ * resolved at runtime and match what the TypePHP runtime itself registers.
+ */
+function main(): int
+{
+    try {
+        $server = new McpServer(RepoRoot::detect());
+        $input = fopen('php://stdin', 'r');
+        $output = fopen('php://stdout', 'w');
+        $errors = fopen('php://stderr', 'w');
+        if (!is_resource($input) || !is_resource($output) || !is_resource($errors)) {
+            return 1;
+        }
+
+        // Diagnostic (stderr only): report the server's working directory and the
+        // auto-detected project dirs so the user can confirm whether the host
+        // launches the server with cwd = the open workspace (pure-auto path) or
+        // whether the explicit TYPEPHP_MCP_PROJECT_ROOT env is doing the work.
+        $cwd = getcwd();
+        $cwdNormalized = is_string($cwd) ? str_replace('\\', '/', $cwd) : '';
+        $cwdIsProject = $cwdNormalized !== '' && ProjectDetector::isTypePhpProject($cwdNormalized);
+        fwrite($errors, sprintf(
+            "[typephp-mcp] startup cwd=%s cwd_is_typephp_project=%s autoDirs=%s\n",
+            $cwdNormalized ?: '(none)',
+            $cwdIsProject ? 'yes' : 'no',
+            implode(',', $server->getAutoDirs())
+        ));
+        fflush($errors);
+        while (true) {
+            $line = fgets($input);
+            if ($line === false) {
+                break;
+            }
+            $trimmed = trim($line);
+            if ($trimmed === '') {
+                continue;
+            }
+            $response = $server->handleLine($trimmed);
+            if ($response !== null) {
+                fwrite($output, $response . "\n");
+                fflush($output);
+            }
+            // Flush any requests the server wants to send to the client
+            // (e.g. roots/list), so the client can answer them next.
+            foreach ($server->drainOutbound() as $out) {
+                fwrite($output, $out . "\n");
+                fflush($output);
+            }
+        }
+        return 0;
+    } catch (Throwable $error) {
+        $errors = fopen('php://stderr', 'w');
+        if (is_resource($errors)) {
+            fwrite($errors, 'typephp-mcp: ' . $error->getMessage() . PHP_EOL);
+        }
+        return 1;
+    }
+}
diff --git a/tools/typephp-mcp/project.yml b/tools/typephp-mcp/project.yml
new file mode 100644
index 00000000..83eacd33
--- /dev/null
+++ b/tools/typephp-mcp/project.yml
@@ -0,0 +1,18 @@
+name: typephp-mcp
+version: 1.0.0
+mode: bin
+cxx-std: c++17
+
+# PHP extensions the MCP server relies on (compiled into the binary as
+# ZEND_MOD_REQUIRED). stdlib/JSON/pcre cover the protocol and search layers.
+ext-deps:
+  - Core
+  - SPL
+  - date
+  - json
+  - pcre
+  - standard
+
+sources:
+  - main.php
+  - src
diff --git a/tools/typephp-mcp/src/CodeIndex.php b/tools/typephp-mcp/src/CodeIndex.php
new file mode 100644
index 00000000..4d8cca74
--- /dev/null
+++ b/tools/typephp-mcp/src/CodeIndex.php
@@ -0,0 +1,594 @@
+<?php
+
+/**
+ * Live code index over examples/, tests/std/ and src/.
+ *
+ * Line-based grep with enclosing-declaration detection: the compiler's own
+ * symbol model lives in src/ and is not importable here, so signatures are
+ * recovered textually. Deterministic, no cache, bounded work.
+ *
+ * The dirs-aware methods (searchCode, getSymbol, getStubApi, getExample) accept
+ * an optional list of absolute directories. When provided, the tool searches
+ * THOSE directories instead of the bundled aot-compiler repo, so a user can
+ * point it at their own TypePHP project plus its Composer-installed framework
+ * (e.g. vendor/swoole/typephp). Package dirs (vendor/node_modules) are NOT
+ * skipped in that mode, because the framework lives there.
+ */
+final class CodeIndex
+{
+    private const MAX_FILES = 3000;
+
+    private const MAX_FILE_BYTES = 262144;
+
+    // Always ignored: VCS / build / cache junk, never source.
+    private const ALWAYS_SKIP = ['.git', 'build', '.phpunit.cache', '.idea'];
+    // Only ignored when scanning the bundled repo (default roots), not when the
+    // caller passes explicit dirs (the framework ships inside vendor/).
+    private const PKG_SKIP = ['vendor', 'node_modules'];
+
+    private RepoRoot $root;
+
+    /**
+     * @var array<int, string> Additional search roots auto-detected from the
+     *   client's open workspace (via MCP roots) and/or TYPEPHP_MCP_PROJECT_ROOT:
+     *   TypePHP project directories plus their installed vendor/swoole/typephp.
+     *   When no explicit dirs are given, these are MERGED into the default
+     *   search set (with vendor/node_modules NOT skipped), so the tools also
+     *   cover the user's own project. Explicit dirs always replace this.
+     */
+    private array $autoDirs = [];
+
+    public function __construct(RepoRoot $root)
+    {
+        $this->root = $root;
+    }
+
+    public function setAutoDirs(array $dirs): void
+    {
+        $this->autoDirs = $dirs;
+    }
+
+    public function searchCode(string $query, int $limit, array $dirs = []): string
+    {
+        $query = trim($query);
+        if ($query === '') {
+            return 'Empty query.';
+        }
+        if ($limit < 1) {
+            $limit = 1;
+        }
+        if ($limit > 30) {
+            $limit = 30;
+        }
+
+        $userDirs = $this->validateDirs($dirs);
+        $userMode = $userDirs !== [];
+        $roots = $userDirs;
+
+        if ($userMode) {
+            $skip = [];
+            $keep = $userDirs;
+        } else {
+            $skip = [$this->root->examplesPath(), $this->root->stdlibTestsPath(), $this->root->srcPath()];
+            $keep = $this->autoDirs;
+        }
+
+        $files = $this->collectFilesFrom($skip, $keep);
+        $hits = [];
+        foreach ($files as $file) {
+            if (count($hits) >= $limit) {
+                break;
+            }
+            $perFile = 0;
+            $lines = $this->readLines($file);
+            foreach ($lines as $index => $line) {
+                if (!TextUtil::contains($line, $query)) {
+                    continue;
+                }
+                $relative = $this->displayPath($roots, $file, $userMode);
+                $declaration = $this->enclosingDeclaration($lines, (int) $index);
+                $hits[] = $relative . ':' . ($index + 1) . ($declaration !== '' ? '  in ' . $declaration : '');
+                $perFile++;
+                if ($perFile >= 3 || count($hits) >= $limit) {
+                    break;
+                }
+            }
+        }
+        if (count($hits) === 0) {
+            return 'No code matches for: ' . $query;
+        }
+        return TextUtil::clip(implode("\n", $hits), 4000);
+    }
+
+    public function getSymbol(string $name, array $dirs = []): string
+    {
+        $name = trim($name);
+        if ($name === '' || preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $name) !== 1) {
+            return 'Invalid symbol name (expected [A-Za-z_][A-Za-z0-9_]*): ' . $name;
+        }
+        $pattern = '/^\s*(?:(?:public|private|protected)\s+)?(?:(?:static|final|abstract|readonly)\s+)*'
+            . '(?:function|class|interface|trait|enum)\s+' . preg_quote($name, '/') . '\b/';
+        $constPattern = '/^\s*const\s+' . preg_quote($name, '/') . '\b/';
+
+        $userDirs = $this->validateDirs($dirs);
+        $userMode = $userDirs !== [];
+        $roots = $userDirs;
+
+        if ($userMode) {
+            $skip = [];
+            $keep = $userDirs;
+        } else {
+            $skip = [$this->root->srcPath(), $this->root->examplesPath(), $this->root->stdlibTestsPath()];
+            $keep = $this->autoDirs;
+        }
+
+        $files = $this->collectFilesFrom($skip, $keep);
+        $hits = [];
+        foreach ($files as $file) {
+            if (count($hits) >= 15) {
+                break;
+            }
+            $lines = $this->readLines($file);
+            foreach ($lines as $index => $line) {
+                if (preg_match($pattern, $line) !== 1 && preg_match($constPattern, $line) !== 1) {
+                    continue;
+                }
+                $signature = trim($line);
+                if (strlen($signature) > 200) {
+                    $signature = TextUtil::clip($signature, 200);
+                }
+                $hits[] = $this->displayPath($roots, $file, $userMode) . ':' . ($index + 1) . '  ' . $signature;
+                if (count($hits) >= 15) {
+                    break;
+                }
+            }
+        }
+        if (count($hits) === 0) {
+            return 'No symbol found for: ' . $name
+                . ($userMode ? ' (searched provided dirs)' : ' (searched src/, examples/, tests/std/)');
+        }
+        return TextUtil::clip(implode("\n", $hits), 4000);
+    }
+
+    public function getExample(string $name, array $dirs = []): string
+    {
+        $name = trim($name);
+        if ($name === '' || preg_match('/^[A-Za-z0-9._-]+$/', $name) !== 1) {
+            return 'Invalid example name (expected [A-Za-z0-9._-]): ' . $name;
+        }
+        $userDirs = $this->validateDirs($dirs);
+        if ($userDirs === []) {
+            $filePath = $this->root->examplesPath() . '/' . $name . '.php';
+            if (is_file($filePath)) {
+                return $this->renderFile($filePath, 4000);
+            }
+            $dirPath = $this->root->examplesPath() . '/' . $name;
+            if (is_dir($dirPath)) {
+                return $this->renderExampleDir($name, $dirPath);
+            }
+            foreach ($this->autoDirs as $base) {
+                $fp = $base . '/' . $name . '.php';
+                if (is_file($fp)) {
+                    return $this->renderFile($fp, 4000, $base);
+                }
+                $dp = $base . '/' . $name;
+                if (is_dir($dp)) {
+                    return $this->renderExampleDir($name, $dp, $base);
+                }
+            }
+            return 'Example not found: ' . $name . "\nUse list_stdlib or search_docs to discover names; examples live in examples/.";
+        }
+        foreach ($userDirs as $base) {
+            $filePath = $base . '/' . $name . '.php';
+            if (is_file($filePath)) {
+                return $this->renderFile($filePath, 4000, $base);
+            }
+            $dirPath = $base . '/' . $name;
+            if (is_dir($dirPath)) {
+                return $this->renderExampleDir($name, $dirPath, $base);
+            }
+        }
+        return 'Example not found in provided dirs: ' . $name;
+    }
+
+    public function getStubApi(string $path, array $dirs = []): string
+    {
+        $userDirs = $this->validateDirs($dirs);
+        $userMode = $userDirs !== [];
+        if ($path === '') {
+            $lines = [];
+            if ($userMode) {
+                foreach ($this->collectStubFiles($userDirs, false) as $file) {
+                    $lines[] = $this->displayPath($userDirs, $file, true);
+                }
+            } else {
+                foreach ($this->collectStubFiles([$this->root->path()], true) as $file) {
+                    $lines[] = $this->displayPath([], $file, false);
+                }
+                foreach ($this->autoDirs as $dir) {
+                    foreach ($this->collectDir($dir, false) as $file) {
+                        if (str_ends_with($file, '.stub.php')) {
+                            $lines[] = $this->displayPath([], $file, false);
+                        }
+                    }
+                }
+            }
+            if (count($lines) === 0) {
+                return 'No .stub.php files found.';
+            }
+            return TextUtil::clip(implode("\n", $lines), 4000);
+        }
+        if ($userMode) {
+            $resolved = $this->resolveInsideAny($userDirs, $path);
+        } else {
+            $resolved = $this->root->resolveInside($path);
+            if ($resolved === null || !is_file($resolved)) {
+                // Default mode also resolves paths against auto-detected
+                // project dirs, so a project stub can be read by relative path.
+                $resolved = $this->resolveInsideAny($this->autoDirs, $path);
+            }
+        }
+        if ($resolved === null || !is_file($resolved)) {
+            return 'Stub file not found'
+                . ($userMode ? ' inside the provided dirs' : ' inside the repository or detected project')
+                . ': ' . $path;
+        }
+        if (!str_ends_with($resolved, '.stub.php')) {
+            return 'Not a .stub.php file: ' . $path;
+        }
+        return $this->renderFile($resolved, 4000);
+    }
+
+    public function listStdlib(string $category): string
+    {
+        $base = $this->root->stdlibTestsPath();
+        if (!is_dir($base)) {
+            return 'tests/std not found.';
+        }
+        if ($category === '') {
+            $entries = scandir($base);
+            if (!is_array($entries)) {
+                return 'tests/std is not readable.';
+            }
+            $lines = [];
+            foreach ($entries as $entry) {
+                if ($entry === '.' || $entry === '..' || !is_dir($base . '/' . $entry)) {
+                    continue;
+                }
+                $tests = $this->phptFiles($base . '/' . $entry);
+                $lines[] = $entry . ' (' . count($tests) . ' tests)';
+            }
+            sort($lines);
+            $lines[] = '';
+            $lines[] = 'std:: surface docs: docs/zh-cn/STD_CONTAINERS.md, HIGH_PRECISION_TYPES.md,'
+                . ' COMPILE_TIME_FUNCTIONS.md, UNIVERSAL_METHODS.md';
+            return implode("\n", $lines);
+        }
+        if (preg_match('/^[A-Za-z0-9_-]+$/', $category) !== 1) {
+            return 'Invalid category name: ' . $category;
+        }
+        $dir = $base . '/' . $category;
+        if (!is_dir($dir)) {
+            return 'Unknown stdlib category: ' . $category . "\nCall list_stdlib without a category to list them.";
+        }
+        $lines = [];
+        foreach ($this->phptFiles($dir) as $test) {
+            $title = $this->phptTitle($test);
+            $lines[] = basename($test) . ($title !== '' ? ' - ' . $title : '');
+            if (count($lines) >= 80) {
+                break;
+            }
+        }
+        if (count($lines) === 0) {
+            return 'No tests in category: ' . $category;
+        }
+        return TextUtil::clip(implode("\n", $lines), 4000);
+    }
+
+    /**
+     * Validate and normalize a caller-supplied dirs list.
+     *
+     * Returns [] when no dirs were provided (caller should use default roots).
+     * Throws when dirs were provided but none resolve to an existing directory.
+     * Drops a directory that is contained within another listed directory to
+     * avoid redundant traversal.
+     *
+     * @param array<int|string, mixed> $dirs
+     * @return array<int, string>
+     */
+    private function validateDirs(array $dirs): array
+    {
+        if (!is_array($dirs) || $dirs === []) {
+            return [];
+        }
+        $valid = [];
+        foreach ($dirs as $entry) {
+            if (!is_string($entry)) {
+                continue;
+            }
+            $real = realpath($entry);
+            if (is_string($real) && is_dir($real)) {
+                // Normalize to forward slashes so displayPath()/resolveInsideAny()
+                // prefix checks are portable across Windows and Linux.
+                $valid[] = str_replace('\\', '/', $real);
+            }
+        }
+        if ($valid === []) {
+            throw new RuntimeException('dirs: none of the provided paths are existing directories.');
+        }
+        sort($valid);
+        $kept = [];
+        foreach ($valid as $candidate) {
+            $contained = false;
+            foreach ($kept as $already) {
+                if ($candidate === $already || str_starts_with($candidate . '/', $already . '/')) {
+                    $contained = true;
+                    break;
+                }
+            }
+            if (!$contained) {
+                $kept[] = $candidate;
+            }
+        }
+        return $kept;
+    }
+
+    /**
+     * Display path for a hit: relative to the matching root in user mode,
+     * otherwise relative to the bundled repo root (unchanged default output).
+     *
+     * @param array<int, string> $roots
+     */
+    private function displayPath(array $roots, string $file, bool $userMode): string
+    {
+        if ($userMode) {
+            foreach ($roots as $root) {
+                $prefix = $root . '/';
+                if (str_starts_with($file, $prefix)) {
+                    return substr($file, strlen($prefix));
+                }
+            }
+        } else {
+            // Default mode: also strip an auto-detected project root so user
+            // project files show a readable relative path, not an absolute one.
+            foreach ($this->autoDirs as $root) {
+                $prefix = $root . '/';
+                if (str_starts_with($file, $prefix)) {
+                    return substr($file, strlen($prefix));
+                }
+            }
+        }
+        return $this->root->relativeFrom($file);
+    }
+
+    /**
+     * Resolve a repo-relative path against any of the given roots, rejecting
+     * traversal and paths escaping every root.
+     *
+     * @param array<int, string> $roots
+     */
+    private function resolveInsideAny(array $roots, string $relative): ?string
+    {
+        $relative = str_replace('\\', '/', $relative);
+        if ($relative === '' || str_contains($relative, '..')) {
+            return null;
+        }
+        foreach ($roots as $root) {
+            // realpath the root so the prefix comparison is case/separator
+            // consistent with the candidate (Windows canonicalizes d: -> D:).
+            $rootReal = realpath($root);
+            if (!is_string($rootReal)) {
+                continue;
+            }
+            $rootReal = str_replace('\\', '/', $rootReal);
+            $candidate = $rootReal . '/' . ltrim($relative, '/');
+            $real = realpath($candidate);
+            if (is_string($real) && is_file($real)) {
+                $real = str_replace('\\', '/', $real);
+                if (str_starts_with($real, $rootReal . '/')) {
+                    return $real;
+                }
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Collect files from two root groups: $skip (official repo, vendor skipped)
+     * and $keep (user projects, vendor NOT skipped). Used so the auto-merged
+     * project roots are scanned in full while the bundled repo still ignores
+     * its own vendor/.
+     *
+     * @param array<int, string> $skip
+     * @param array<int, string> $keep
+     * @return array<int, string>
+     */
+    private function collectFilesFrom(array $skip, array $keep): array
+    {
+        $files = [];
+        foreach ($skip as $dir) {
+            foreach ($this->collectDir($dir, true) as $file) {
+                $files[] = $file;
+            }
+            if (count($files) >= self::MAX_FILES) {
+                break;
+            }
+        }
+        foreach ($keep as $dir) {
+            foreach ($this->collectDir($dir, false) as $file) {
+                $files[] = $file;
+            }
+            if (count($files) >= self::MAX_FILES) {
+                break;
+            }
+        }
+        sort($files);
+        return $files;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function collectDir(string $dir, bool $skipPackages): array
+    {
+        $result = [];
+        if (!is_dir($dir)) {
+            return $result;
+        }
+        $entries = scandir($dir);
+        if (!is_array($entries)) {
+            return $result;
+        }
+        foreach ($entries as $entry) {
+            if (count($result) >= self::MAX_FILES) {
+                break;
+            }
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            if (in_array($entry, self::ALWAYS_SKIP, true)) {
+                continue;
+            }
+            if ($skipPackages && in_array($entry, self::PKG_SKIP, true)) {
+                continue;
+            }
+            $path = $dir . '/' . $entry;
+            if (is_dir($path)) {
+                $nested = $this->collectDir($path, $skipPackages);
+                foreach ($nested as $file) {
+                    $result[] = $file;
+                }
+            } elseif (str_ends_with($entry, '.php')) {
+                $result[] = $path;
+            }
+        }
+        return $result;
+    }
+
+    /**
+     * @param array<int, string> $roots
+     * @return array<int, string>
+     */
+    private function collectStubFiles(array $roots, bool $skipPackages): array
+    {
+        $files = [];
+        foreach ($roots as $root) {
+            foreach ($this->collectDir($root, $skipPackages) as $file) {
+                if (str_ends_with($file, '.stub.php')) {
+                    $files[] = $file;
+                }
+            }
+        }
+        return $files;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function readLines(string $path): array
+    {
+        $size = filesize($path);
+        if (!is_int($size) || $size <= 0 || $size > self::MAX_FILE_BYTES) {
+            return [];
+        }
+        $content = file_get_contents($path);
+        if (!is_string($content)) {
+            return [];
+        }
+        return explode("\n", $content);
+    }
+
+    /**
+     * @param array<int, string> $lines
+     */
+    private function enclosingDeclaration(array $lines, int $index): string
+    {
+        for ($i = $index; $i >= 0; $i--) {
+            if (preg_match('/^\s*(?:(?:abstract|final|readonly)\s+)?(?:class|interface|trait|enum|function)\s/', $lines[$i]) === 1) {
+                return trim($lines[$i]);
+            }
+        }
+        return '';
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function phptFiles(string $dir): array
+    {
+        $entries = scandir($dir);
+        if (!is_array($entries)) {
+            return [];
+        }
+        $files = [];
+        foreach ($entries as $entry) {
+            if (str_ends_with($entry, '.phpt')) {
+                $files[] = $dir . '/' . $entry;
+            }
+        }
+        sort($files);
+        return $files;
+    }
+
+    private function phptTitle(string $path): string
+    {
+        $lines = $this->readLines($path);
+        if (count($lines) < 2) {
+            return '';
+        }
+        if (trim($lines[0]) !== '--TEST--') {
+            return '';
+        }
+        return trim($lines[1]);
+    }
+
+    private function renderFile(string $path, int $maxBytes, string $base = ''): string
+    {
+        $content = file_get_contents($path);
+        if (!is_string($content)) {
+            return 'Cannot read: ' . $path;
+        }
+        if ($base !== '' && str_starts_with($path, $base . '/')) {
+            $rel = substr($path, strlen($base) + 1);
+        } else {
+            $rel = $this->root->relativeFrom($path);
+        }
+        $header = '# ' . $rel . ' (' . strlen($content) . " bytes)\n";
+        return TextUtil::clip($header . $content, $maxBytes);
+    }
+
+    private function renderExampleDir(string $name, string $dir, string $base = ''): string
+    {
+        $files = $this->collectDir($dir, $base !== '');
+        $relOf = function (string $f) use ($base): string {
+            if ($base !== '' && str_starts_with($f, $base . '/')) {
+                return substr($f, strlen($base) + 1);
+            }
+            return $this->root->relativeFrom($f);
+        };
+        $headerDir = ($base !== '' && str_starts_with($dir, $base . '/'))
+            ? substr($dir, strlen($base) + 1)
+            : $this->root->relativeFrom($dir);
+        $lines = ['# ' . $headerDir . '/ (' . count($files) . ' files)'];
+        foreach ($files as $file) {
+            $lines[] = '  ' . $relOf($file);
+            if (count($lines) >= 60) {
+                break;
+            }
+        }
+        foreach (['README.md', 'main.php', 'project.yml'] as $entry) {
+            $path = $dir . '/' . $entry;
+            if (!is_file($path)) {
+                continue;
+            }
+            $content = file_get_contents($path);
+            if (!is_string($content)) {
+                continue;
+            }
+            $lines[] = '';
+            $lines[] = '--- ' . $entry . ' ---';
+            $lines[] = TextUtil::clip($content, 1500);
+        }
+        return TextUtil::clip(implode("\n", $lines), 4000);
+    }
+}
diff --git a/tools/typephp-mcp/src/CompilerOracle.php b/tools/typephp-mcp/src/CompilerOracle.php
new file mode 100644
index 00000000..5665e62e
--- /dev/null
+++ b/tools/typephp-mcp/src/CompilerOracle.php
@@ -0,0 +1,208 @@
+<?php
+
+/**
+ * L3 compiler oracle: run `php bin/tpc.php --dry` on a file.
+ *
+ * --dry only generates C++, so it validates the TypePHP subset (the #1 AI
+ * failure mode) without compiling or linking. Link-time errors are not
+ * covered; the output says so.
+ *
+ * Note: tpc still detects the host toolchain at startup (it fatals when no
+ * C/C++ compiler is on PATH), so check_code makes sure an MSVC cl is
+ * reachable before spawning the compiler.
+ */
+final class CompilerOracle
+{
+    public static function check(string $file, RepoRoot $root): string
+    {
+        $resolved = $file;
+        if (!is_file($resolved)) {
+            $inside = $root->resolveInside($file);
+            $resolved = is_string($inside) ? $inside : '';
+        }
+        if ($resolved === '' || !is_file($resolved)) {
+            return 'File not found: ' . $file . "\nPass an absolute path, or a path relative to the repo root.";
+        }
+
+        $php = self::phpBinary();
+        if ($php === '') {
+            return "No PHP binary found on PATH. Set TYPEPHP_MCP_PHP to a php executable.\n"
+                . 'check_code needs `php bin/tpc.php --dry` to run the compiler oracle.';
+        }
+
+        self::ensureHostToolchain();
+
+        $buildDir = sys_get_temp_dir() . '/typephp-mcp-dry-' . uniqid();
+        if (!mkdir($buildDir, 0777, true)) {
+            return 'Cannot create build directory: ' . $buildDir;
+        }
+
+        $command = escapeshellarg($php)
+            . ' ' . escapeshellarg($root->path() . '/bin/tpc.php')
+            . ' --dry ' . escapeshellarg($resolved)
+            . ' --build-dir ' . escapeshellarg($buildDir)
+            . ' --no-color --no-progress 2>&1';
+        $output = [];
+        $code = -1;
+        exec($command, $output, $code);
+        self::removeDir($buildDir);
+
+        return self::format($resolved, $code, $output);
+    }
+
+    /**
+     * MCP clients do not always inherit a developer PATH, but tpc resolves the
+     * host toolchain before doing anything else. Prepend the MSVC bin located
+     * through vswhere when no cl is reachable; putenv propagates to the
+     * exec()/proc_open() children of this process on Windows.
+     */
+    private static function ensureHostToolchain(): void
+    {
+        if (stripos(PHP_OS, 'WIN') !== 0) {
+            return;
+        }
+        if (self::hasClOnPath()) {
+            return;
+        }
+        $binDir = self::findMsvcBinDir();
+        if ($binDir === null) {
+            return;
+        }
+        $path = getenv('PATH');
+        putenv('PATH=' . $binDir . ';' . (is_string($path) ? $path : ''));
+    }
+
+    private static function hasClOnPath(): bool
+    {
+        $path = getenv('PATH');
+        if (!is_string($path) || $path === '') {
+            return false;
+        }
+        foreach (explode(';', $path) as $dir) {
+            if ($dir !== '' && is_file($dir . '\cl.exe')) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Locate the newest MSVC x64 host bin directory via vswhere.
+     */
+    protected static function findMsvcBinDir(): ?string
+    {
+        $programFiles = getenv('ProgramFiles(x86)');
+        if (!is_string($programFiles) || $programFiles === '') {
+            // Standard x64 Windows location; the variable may be absent when a
+            // client sanitizes the environment.
+            $programFiles = 'C:\Program Files (x86)';
+        }
+        $vswhere = $programFiles . '\Microsoft Visual Studio\Installer\vswhere.exe';
+        if (!is_file($vswhere)) {
+            return null;
+        }
+        $output = [];
+        $code = -1;
+        exec('"' . $vswhere . '" -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath 2>nul', $output, $code);
+        $installPath = count($output) > 0 && is_string($output[0]) ? trim($output[0]) : '';
+        if ($installPath === '' || !is_dir($installPath)) {
+            return null;
+        }
+        $msvcRoot = $installPath . '\VC\Tools\MSVC';
+        if (!is_dir($msvcRoot)) {
+            return null;
+        }
+        $versions = scandir($msvcRoot);
+        if (!is_array($versions)) {
+            return null;
+        }
+        $latest = '';
+        foreach ($versions as $version) {
+            if ($version === '.' || $version === '..') {
+                continue;
+            }
+            if (is_dir($msvcRoot . '\\' . $version) && strcmp($version, $latest) > 0) {
+                $latest = $version;
+            }
+        }
+        if ($latest === '') {
+            return null;
+        }
+        $binDir = $msvcRoot . '\\' . $latest . '\bin\Hostx64\x64';
+        return is_dir($binDir) ? $binDir : null;
+    }
+
+    public static function phpBinary(): string
+    {
+        $override = getenv('TYPEPHP_MCP_PHP');
+        if (is_string($override) && $override !== '' && is_file($override)) {
+            return $override;
+        }
+        $output = [];
+        $code = -1;
+        exec('php -v 2>&1', $output, $code);
+        if ($code === 0 && count($output) > 0) {
+            return 'php';
+        }
+        return '';
+    }
+
+    private static function format(string $file, int $code, array $output): string
+    {
+        $kept = [];
+        foreach ($output as $line) {
+            if (!is_string($line)) {
+                continue;
+            }
+            $trimmed = trim($line);
+            if ($trimmed === '') {
+                continue;
+            }
+            if (str_starts_with($trimmed, '#')) {
+                continue;
+            }
+            if (str_starts_with($trimmed, 'Stack trace')) {
+                continue;
+            }
+            if (str_starts_with($trimmed, 'thrown in')) {
+                continue;
+            }
+            if (str_starts_with($trimmed, 'Initialized platform')) {
+                continue;
+            }
+            $kept[] = $trimmed;
+        }
+        if (count($kept) > 40) {
+            $kept = array_slice($kept, 0, 40);
+        }
+        $body = implode("\n", $kept);
+        if ($code === 0) {
+            return 'OK: ' . $file . " passes `tpc --dry`.\n"
+                . "Note: --dry covers C++ generation only; link-time errors are not checked.\n" . $body;
+        }
+        return 'FAILED (exit ' . $code . '): ' . $file . "\n" . $body;
+    }
+
+    private static function removeDir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+        $entries = scandir($dir);
+        if (!is_array($entries)) {
+            return;
+        }
+        foreach ($entries as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            $path = $dir . '/' . $entry;
+            if (is_dir($path)) {
+                self::removeDir($path);
+            } else {
+                unlink($path);
+            }
+        }
+        rmdir($dir);
+    }
+}
diff --git a/tools/typephp-mcp/src/Config.php b/tools/typephp-mcp/src/Config.php
new file mode 100644
index 00000000..00f842b1
--- /dev/null
+++ b/tools/typephp-mcp/src/Config.php
@@ -0,0 +1,10 @@
+<?php
+
+/**
+ * Build-time default repository root.
+ *
+ * Detection order at runtime: TYPEPHP_MCP_ROOT env var, then an upward walk
+ * from the current working directory, then this constant. The constant only
+ * matters when the binary is started outside the repository.
+ */
+const TYPEPHP_MCP_DEFAULT_ROOT = 'D:\\git\\php\\aot-compiler';
diff --git a/tools/typephp-mcp/src/DocIndex.php b/tools/typephp-mcp/src/DocIndex.php
new file mode 100644
index 00000000..a5c5fbb3
--- /dev/null
+++ b/tools/typephp-mcp/src/DocIndex.php
@@ -0,0 +1,294 @@
+<?php
+
+/**
+ * Live documentation index over docs/<lang>/*.md.
+ *
+ * Chunks are split on ATX headings and carry heading_path + line numbers so
+ * results always cite docs/<lang>/<file>.md#<heading> (L<line>). No prebuilt
+ * database: the corpus is ~2 MB and is read on first use, which also removes
+ * index staleness by construction.
+ */
+final class DocIndex
+{
+    private RepoRoot $root;
+
+    /** @var array<int, array{lang: string, file: string, anchor: string, line: int, text: string}>|null */
+    private ?array $chunks = null;
+
+    public function __construct(RepoRoot $root)
+    {
+        $this->root = $root;
+    }
+
+    public function listTopics(): string
+    {
+        $lines = [];
+        foreach ($this->languages() as $lang) {
+            foreach ($this->docNames($lang) as $name) {
+                $title = $this->docTitle($lang, $name);
+                $lines[] = '[' . $lang . '] ' . $name . ($title !== '' ? ' - ' . $title : '');
+            }
+        }
+        if (count($lines) === 0) {
+            return 'No markdown docs found under ' . $this->root->docsPath('zh-cn');
+        }
+        return TextUtil::clip(implode("\n", $lines), 6000);
+    }
+
+    public function search(string $query, string $lang, int $limit): string
+    {
+        $terms = TextUtil::terms($query);
+        if (count($terms) === 0) {
+            return 'Empty query.';
+        }
+        if ($limit < 1) {
+            $limit = 1;
+        }
+        if ($limit > 10) {
+            $limit = 10;
+        }
+
+        $scored = [];
+        foreach ($this->loadChunks() as $index => $chunk) {
+            if ($lang !== '' && $lang !== 'all' && $chunk['lang'] !== $lang) {
+                continue;
+            }
+            $chunkScore = 0;
+            foreach ($terms as $term) {
+                $chunkScore += $this->scoreTerm($chunk, $term);
+            }
+            if ($chunkScore > 0) {
+                $scored[$index] = $chunkScore;
+            }
+        }
+        if (count($scored) === 0) {
+            return 'No doc matches for: ' . $query;
+        }
+
+        $picked = [];
+        for ($round = 0; $round < $limit; $round++) {
+            $bestIndex = -1;
+            $bestScore = 0;
+            foreach ($scored as $index => $score) {
+                $value = (int) $score;
+                if ($value > $bestScore) {
+                    $bestScore = $value;
+                    $bestIndex = (int) $index;
+                }
+            }
+            if ($bestIndex < 0) {
+                break;
+            }
+            $picked[] = $bestIndex;
+            unset($scored[$bestIndex]);
+        }
+
+        $chunks = $this->loadChunks();
+        $blocks = [];
+        $budget = 4000;
+        foreach ($picked as $index) {
+            $chunk = $chunks[$index];
+            $header = '[' . $chunk['lang'] . '] docs/' . $chunk['lang'] . '/' . $chunk['file']
+                . ($chunk['anchor'] !== $chunk['file'] ? '#' . $chunk['anchor'] : '')
+                . ' (L' . $chunk['line'] . ')';
+            $excerpt = $this->excerptAround($chunk['text'], $terms);
+            $block = $header . "\n" . $excerpt;
+            if (strlen($block) > $budget) {
+                $block = TextUtil::clip($block, $budget);
+            }
+            $blocks[] = $block;
+            $budget -= (int) strlen($block);
+            if ($budget < 400) {
+                break;
+            }
+        }
+        return implode("\n\n", $blocks);
+    }
+
+    public function changelog(string $version): string
+    {
+        $path = $this->root->path() . '/CHANGELOG.md';
+        $content = is_file($path) ? file_get_contents($path) : false;
+        if (!is_string($content) || $content === '') {
+            return 'CHANGELOG.md not found.';
+        }
+        $sections = preg_split('/^## /m', $content);
+        if (!is_array($sections) || count($sections) < 2) {
+            return TextUtil::clip($content, 4000);
+        }
+        $headings = [];
+        for ($i = 1; $i < count($sections); $i++) {
+            $lines = explode("\n", $sections[$i]);
+            $headings[] = trim($lines[0]);
+        }
+        foreach ($sections as $section) {
+            if ($section === $sections[0]) {
+                continue;
+            }
+            $lines = explode("\n", $section);
+            $heading = trim($lines[0]);
+            if ($version === '' || str_starts_with($heading, $version)) {
+                return TextUtil::clip('## ' . $section, 4000);
+            }
+        }
+        if ($version === '') {
+            return TextUtil::clip('## ' . $sections[1], 4000);
+        }
+        return 'No changelog section for version: ' . $version . "\nAvailable: " . implode(', ', $headings);
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function languages(): array
+    {
+        return ['zh-cn', 'en'];
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function docNames(string $lang): array
+    {
+        $dir = $this->root->docsPath($lang);
+        if (!is_dir($dir)) {
+            return [];
+        }
+        $entries = scandir($dir);
+        if (!is_array($entries)) {
+            return [];
+        }
+        $names = [];
+        foreach ($entries as $entry) {
+            if (str_ends_with($entry, '.md')) {
+                $names[] = $entry;
+            }
+        }
+        sort($names);
+        return $names;
+    }
+
+    private function docTitle(string $lang, string $name): string
+    {
+        $content = file_get_contents($this->root->docsPath($lang) . '/' . $name);
+        if (!is_string($content)) {
+            return '';
+        }
+        $lines = explode("\n", $content);
+        foreach ($lines as $line) {
+            if (str_starts_with($line, '# ')) {
+                return trim(substr($line, 2));
+            }
+        }
+        return '';
+    }
+
+    /**
+     * @return array<int, array{lang: string, file: string, anchor: string, line: int, text: string}>
+     */
+    private function loadChunks(): array
+    {
+        if ($this->chunks !== null) {
+            return $this->chunks;
+        }
+        $chunks = [];
+        foreach ($this->languages() as $lang) {
+            foreach ($this->docNames($lang) as $name) {
+                $fileChunks = $this->chunkFile($lang, $name);
+                foreach ($fileChunks as $chunk) {
+                    $chunks[] = $chunk;
+                }
+            }
+        }
+        $this->chunks = $chunks;
+        return $chunks;
+    }
+
+    /**
+     * @return array<int, array{lang: string, file: string, anchor: string, line: int, text: string}>
+     */
+    private function chunkFile(string $lang, string $name): array
+    {
+        $content = file_get_contents($this->root->docsPath($lang) . '/' . $name);
+        if (!is_string($content) || $content === '') {
+            return [];
+        }
+        $lines = explode("\n", $content);
+        $chunks = [];
+        $anchor = $name;
+        $buffer = [];
+        $startLine = 1;
+        foreach ($lines as $offset => $line) {
+            $lineNo = (int) ($offset + 1);
+            if (preg_match('/^(#{1,6})\s+(.+?)\s*$/', $line, $matches) === 1) {
+                if (count($buffer) > 0) {
+                    $chunks[] = [
+                        'lang' => $lang,
+                        'file' => $name,
+                        'anchor' => $anchor,
+                        'line' => $startLine,
+                        'text' => implode("\n", $buffer),
+                    ];
+                }
+                $anchor = (string) $matches[2];
+                $buffer = [$line];
+                $startLine = $lineNo;
+            } else {
+                $buffer[] = $line;
+            }
+        }
+        if (count($buffer) > 0) {
+            $chunks[] = [
+                'lang' => $lang,
+                'file' => $name,
+                'anchor' => $anchor,
+                'line' => $startLine,
+                'text' => implode("\n", $buffer),
+            ];
+        }
+        return $chunks;
+    }
+
+    /**
+     * @param array{lang: string, file: string, anchor: string, line: int, text: string} $chunk
+     */
+    private function scoreTerm(array $chunk, string $term): int
+    {
+        $text = strtolower($chunk['text']);
+        $count = (int) substr_count($text, $term);
+        if ($count === 0) {
+            return 0;
+        }
+        $score = $count;
+        if (substr_count(strtolower($chunk['anchor']), $term) > 0) {
+            $score += 8;
+        }
+        if (substr_count(strtolower($chunk['file']), $term) > 0) {
+            $score += 4;
+        }
+        return $score;
+    }
+
+    /**
+     * @param array{lang: string, file: string, anchor: string, line: int, text: string} $chunk
+     * @param array<int, string> $terms
+     */
+    private function excerptAround(string $text, array $terms): string
+    {
+        $position = -1;
+        foreach ($terms as $term) {
+            $found = stripos($text, $term);
+            if ($found !== false && ($position < 0 || $found < $position)) {
+                $position = (int) $found;
+            }
+        }
+        if ($position < 0) {
+            $position = 0;
+        }
+        $start = $position - 120;
+        if ($start < 0) {
+            $start = 0;
+        }
+        return TextUtil::utf8SafeSlice($text, $start, 480);
+    }
+}
diff --git a/tools/typephp-mcp/src/IndexInfo.php b/tools/typephp-mcp/src/IndexInfo.php
new file mode 100644
index 00000000..f6c273ac
--- /dev/null
+++ b/tools/typephp-mcp/src/IndexInfo.php
@@ -0,0 +1,90 @@
+<?php
+
+final class IndexInfo
+{
+    /**
+     * @param array<int, string> $toolNames
+     * @param array<int, string> $projectDirs
+     */
+    public static function render(RepoRoot $root, array $toolNames, array $projectDirs = []): string
+    {
+        $lines = [];
+        $lines[] = 'repo_root: ' . $root->path();
+        $lines[] = 'server: typephp-mcp ' . ToolDefinitions::SERVER_VERSION . ' (TypePHP AOT native binary)';
+        $lines[] = 'protocol: ' . McpServer::PROTOCOL_VERSION;
+        $lines[] = 'tpc_version: ' . self::tpcVersion($root);
+        $lines[] = 'git_commit: ' . self::gitCommit($root);
+        $lines[] = 'docs: ' . self::countDocs($root, 'zh-cn') . ' zh-cn + '
+            . self::countDocs($root, 'en') . ' en markdown files';
+        $lines[] = 'tools (' . count($toolNames) . '): ' . implode(', ', $toolNames);
+        $cwd = getcwd();
+        $cwdNorm = is_string($cwd) ? str_replace('\\', '/', $cwd) : '';
+        $lines[] = 'server_cwd: ' . ($cwdNorm ?: '(none)');
+        if ($cwdNorm !== '') {
+            $lines[] = 'server_cwd_is_typephp_project: ' . (ProjectDetector::isTypePhpProject($cwdNorm) ? 'yes' : 'no');
+        }
+        if ($projectDirs === []) {
+            $lines[] = 'project_dirs: (none auto-detected; set TYPEPHP_MCP_PROJECT_ROOT or open a TypePHP project)';
+        } else {
+            $lines[] = 'project_dirs (' . count($projectDirs) . '): ' . implode(', ', $projectDirs);
+        }
+        $lines[] = 'staleness: no prebuilt index - docs/examples/src are read live on each call,'
+            . ' so results always match this checkout. Rebuild the server after upgrading tpc.';
+        return implode("\n", $lines);
+    }
+
+    private static function tpcVersion(RepoRoot $root): string
+    {
+        $php = CompilerOracle::phpBinary();
+        if ($php === '') {
+            return 'unknown (no php on PATH; set TYPEPHP_MCP_PHP)';
+        }
+        $output = [];
+        $code = -1;
+        exec(escapeshellarg($php) . ' ' . escapeshellarg($root->path() . '/bin/tpc.php')
+            . ' --version --no-color 2>&1', $output, $code);
+        if ($code !== 0) {
+            return 'unknown';
+        }
+        foreach ($output as $line) {
+            if (is_string($line) && preg_match('/v\d+\.\d+\.\d+/', $line, $m) === 1) {
+                return $m[0];
+            }
+        }
+        return 'unknown';
+    }
+
+    private static function gitCommit(RepoRoot $root): string
+    {
+        $output = [];
+        $code = -1;
+        exec('git -C ' . escapeshellarg($root->path()) . ' rev-parse --short HEAD 2>&1', $output, $code);
+        if ($code !== 0 || count($output) === 0) {
+            return 'unknown';
+        }
+        $commit = trim((string) $output[0]);
+        if ($commit === '' || str_starts_with($commit, 'fatal')) {
+            return 'unknown';
+        }
+        return $commit;
+    }
+
+    private static function countDocs(RepoRoot $root, string $lang): int
+    {
+        $dir = $root->docsPath($lang);
+        if (!is_dir($dir)) {
+            return 0;
+        }
+        $entries = scandir($dir);
+        if (!is_array($entries)) {
+            return 0;
+        }
+        $count = 0;
+        foreach ($entries as $entry) {
+            if (str_ends_with($entry, '.md')) {
+                $count++;
+            }
+        }
+        return $count;
+    }
+}
diff --git a/tools/typephp-mcp/src/McpServer.php b/tools/typephp-mcp/src/McpServer.php
new file mode 100644
index 00000000..ac4136f4
--- /dev/null
+++ b/tools/typephp-mcp/src/McpServer.php
@@ -0,0 +1,435 @@
+<?php
+
+/**
+ * Minimal MCP server over newline-delimited JSON-RPC 2.0 on stdio.
+ *
+ * Supported: initialize, ping, tools/list, tools/call, and notifications
+ * (messages without an id are never answered).
+ */
+final class McpServer
+{
+    public const PROTOCOL_VERSION = '2024-11-05';
+
+    private RepoRoot $root;
+
+    private ?DocIndex $docIndex = null;
+
+    private ?CodeIndex $codeIndex = null;
+
+    /** @var array<int, string> Search roots auto-detected from the client's
+     *   open workspace (MCP roots) and/or TYPEPHP_MCP_PROJECT_ROOT. */
+    private array $autoDirs = [];
+
+    /** @var array<int, string> JSON-RPC requests the server must send to the
+     *   client (e.g. roots/list); drained by the I/O loop. */
+    private array $outbound = [];
+
+    private ?int $rootsRequestId = null;
+
+    private bool $clientSupportsRoots = false;
+
+    private int $nextRequestId = 1;
+
+    public function __construct(RepoRoot $root)
+    {
+        $this->root = $root;
+        $this->seedFromEnv();
+        $this->seedFromCwd();
+    }
+
+    /**
+     * TYPEPHP_MCP_PROJECT_ROOT (single path or ;/-separated list) seeds the
+     * auto-detected project dirs even when the client does not send MCP roots.
+     */
+    private function seedFromEnv(): void
+    {
+        $raw = getenv('TYPEPHP_MCP_PROJECT_ROOT');
+        if (!is_string($raw) || $raw === '') {
+            return;
+        }
+        foreach (preg_split('#[;:]+#', $raw) ?: [] as $entry) {
+            $entry = trim((string) $entry);
+            if ($entry === '') {
+                continue;
+            }
+            $entry = str_replace('\\', '/', $entry);
+            if (ProjectDetector::isTypePhpProject($entry)) {
+                foreach (ProjectDetector::searchDirs($entry) as $dir) {
+                    $this->addAutoDir($dir);
+                }
+            }
+        }
+    }
+
+    private function addAutoDir(string $dir): void
+    {
+        $dir = rtrim(str_replace('\\', '/', $dir), '/');
+        if (!is_dir($dir) || in_array($dir, $this->autoDirs, true)) {
+            return;
+        }
+        $this->autoDirs[] = $dir;
+    }
+
+    /**
+     * Best-effort, cross-IDE auto-detection: many MCP hosts (Claude Code, and
+     * several IDE integrations) launch the server with the working directory set
+     * to the open workspace. Walk up from cwd and, for the nearest TypePHP
+     * project found, merge it into the default search set. This needs no client
+     * cooperation (unlike MCP roots) and works regardless of which agent IDE is
+     * hosting the server. The bundled compiler repo itself is skipped, since it
+     * is already the default search root.
+     */
+    private function seedFromCwd(): void
+    {
+        $cwd = getcwd();
+        if (!is_string($cwd) || $cwd === '') {
+            return;
+        }
+        // Normalize the official repo path to forward slashes so the comparison
+        // below is separator/case-insensitive across Windows and Linux.
+        $officialRaw = $this->root->path();
+        $official = str_replace('\\', '/', is_string($r = realpath($officialRaw)) ? $r : $officialRaw);
+        $dir = str_replace('\\', '/', $cwd);
+        for ($depth = 0; $depth < 6; $depth++) {
+            $real = realpath($dir);
+            $check = is_string($real) ? str_replace('\\', '/', $real) : $dir;
+            if (ProjectDetector::isTypePhpProject($check)) {
+                $isOfficial = $check === $official || str_starts_with($check . '/', $official . '/');
+                if (!$isOfficial) {
+                    foreach (ProjectDetector::searchDirs($check) as $d) {
+                        $this->addAutoDir($d);
+                    }
+                }
+                return;
+            }
+            $parent = dirname($dir);
+            if ($parent === $dir) {
+                break;
+            }
+            $dir = $parent;
+        }
+    }
+
+    /**
+     * Handle one raw line. Returns the JSON reply, or null for notifications.
+     */
+    public function handleLine(string $line): ?string
+    {
+        // Some hosts pipe stdin through text encoders that prepend a UTF-8
+        // BOM; json_decode rejects the first line otherwise.
+        if (str_starts_with($line, "\xEF\xBB\xBF")) {
+            $line = substr($line, 3);
+        }
+        $decoded = json_decode($line, true);
+        if (!is_array($decoded)) {
+            return $this->encode(['jsonrpc' => '2.0', 'id' => null, 'error' => [
+                'code' => -32700,
+                'message' => 'Parse error',
+            ]]);
+        }
+
+        $hasId = array_key_exists('id', $decoded);
+        $id = $hasId ? $decoded['id'] : null;
+        $method = isset($decoded['method']) && is_string($decoded['method']) ? $decoded['method'] : '';
+        // A JSON-RPC response (id + result/error, no method) to a request we
+        // sent (e.g. roots/list) is consumed, never answered.
+        if ($method === '' && $hasId && (isset($decoded['result']) || isset($decoded['error']))) {
+            if ($this->rootsRequestId !== null && $id === $this->rootsRequestId) {
+                if (isset($decoded['result'])) {
+                    $this->consumeRootsResponse($decoded['result']);
+                }
+                $this->rootsRequestId = null;
+            }
+            return null;
+        }
+        if ($method === '') {
+            if (!$hasId) {
+                return null;
+            }
+            return $this->error($id, -32600, 'Invalid Request: missing method');
+        }
+
+        if ($method === 'initialize') {
+            // Echo the client's requested protocol version when it offers one;
+            // this server only implements the tools capability, which is
+            // version-independent. Picky clients reject a downgrade answer.
+            $requested = '';
+            $params = isset($decoded['params']) && is_array($decoded['params']) ? $decoded['params'] : [];
+            if (isset($params['protocolVersion']) && is_string($params['protocolVersion']) && $params['protocolVersion'] !== '') {
+                $requested = $params['protocolVersion'];
+            }
+            $clientCaps = isset($params['capabilities']) && is_array($params['capabilities']) ? $params['capabilities'] : [];
+            $this->clientSupportsRoots = isset($clientCaps['roots']);
+            return $this->result($id, [
+                'protocolVersion' => $requested !== '' ? $requested : self::PROTOCOL_VERSION,
+                'capabilities' => ['tools' => (object)[], 'roots' => (object)[]],
+                'serverInfo' => [
+                    'name' => 'typephp-mcp',
+                    'version' => ToolDefinitions::SERVER_VERSION,
+                ],
+                'instructions' => Restrictions::summary(),
+            ]);
+        }
+        if ($method === 'ping') {
+            return $this->result($id, (object)[]);
+        }
+        if ($method === 'notifications/initialized') {
+            // The client is ready: ask it for the open workspace so we can
+            // auto-detect TypePHP projects. Only if the client advertised the
+            // roots capability.
+            if ($this->clientSupportsRoots) {
+                $this->enqueueRootsList();
+            }
+            return null;
+        }
+        if ($method === 'notifications/roots/list_changed') {
+            if ($this->clientSupportsRoots) {
+                $this->enqueueRootsList();
+            }
+            return null;
+        }
+        if ($method === 'tools/list') {
+            return $this->result($id, ['tools' => ToolDefinitions::all()]);
+        }
+        if ($method === 'tools/call') {
+            return $this->handleToolCall($id, $decoded);
+        }
+        // This server exposes tools only. Answer the other standard list
+        // methods with empty results instead of -32601: clients that probe
+        // all capabilities in parallel treat an error reply as a failed
+        // listing and then report "0 tools".
+        if ($method === 'prompts/list') {
+            return $this->result($id, ['prompts' => []]);
+        }
+        if ($method === 'resources/list') {
+            return $this->result($id, ['resources' => []]);
+        }
+        if ($method === 'resources/templates/list') {
+            return $this->result($id, ['resourceTemplates' => []]);
+        }
+        if ($method === 'logging/setLevel') {
+            return $this->result($id, (object)[]);
+        }
+
+        if (!$hasId) {
+            return null;
+        }
+        return $this->error($id, -32601, 'Method not found: ' . $method);
+    }
+
+    private function handleToolCall(int|string|null $id, array $request): string
+    {
+        $params = isset($request['params']) && is_array($request['params']) ? $request['params'] : [];
+        $name = isset($params['name']) && is_string($params['name']) ? $params['name'] : '';
+        $arguments = isset($params['arguments']) && is_array($params['arguments']) ? $params['arguments'] : [];
+
+        $known = ToolDefinitions::names();
+        if (!in_array($name, $known, true)) {
+            return $this->error($id, -32602, 'Unknown tool: ' . $name);
+        }
+
+        try {
+            $text = $this->dispatchTool($name, $arguments);
+        } catch (Throwable $error) {
+            return $this->result($id, [
+                'content' => [['type' => 'text', 'text' => 'Tool error: ' . $error->getMessage()]],
+                'isError' => true,
+            ]);
+        }
+        return $this->result($id, [
+            'content' => [['type' => 'text', 'text' => $text]],
+        ]);
+    }
+
+    private function dispatchTool(string $name, array $arguments): string
+    {
+        if ($name === 'check_code') {
+            return CompilerOracle::check(self::argString($arguments, 'path', ''), $this->root);
+        }
+        if ($name === 'list_restrictions') {
+            return Restrictions::render(self::argString($arguments, 'topic', ''));
+        }
+        if ($name === 'list_topics') {
+            return $this->docs()->listTopics();
+        }
+        if ($name === 'search_docs') {
+            return $this->docs()->search(
+                self::argString($arguments, 'query', ''),
+                self::argString($arguments, 'lang', 'zh-cn'),
+                self::argInt($arguments, 'limit', 5)
+            );
+        }
+        if ($name === 'get_changelog') {
+            return $this->docs()->changelog(self::argString($arguments, 'version', ''));
+        }
+        if ($name === 'search_code') {
+            return $this->code()->searchCode(
+                self::argString($arguments, 'query', ''),
+                self::argInt($arguments, 'limit', 15),
+                self::argArray($arguments, 'dirs')
+            );
+        }
+        if ($name === 'get_symbol') {
+            return $this->code()->getSymbol(
+                self::argString($arguments, 'name', ''),
+                self::argArray($arguments, 'dirs')
+            );
+        }
+        if ($name === 'get_example') {
+            return $this->code()->getExample(
+                self::argString($arguments, 'name', ''),
+                self::argArray($arguments, 'dirs')
+            );
+        }
+        if ($name === 'get_stub_api') {
+            return $this->code()->getStubApi(
+                self::argString($arguments, 'path', ''),
+                self::argArray($arguments, 'dirs')
+            );
+        }
+        if ($name === 'list_stdlib') {
+            return $this->code()->listStdlib(self::argString($arguments, 'category', ''));
+        }
+        if ($name === 'get_build_config_help') {
+            return Restrictions::render('build') . "\n\n" . Restrictions::render('stub');
+        }
+        return $this->renderIndexInfo();
+    }
+
+    private function renderIndexInfo(): string
+    {
+        return IndexInfo::render($this->root, ToolDefinitions::names(), $this->autoDirs);
+    }
+
+    private function docs(): DocIndex
+    {
+        if ($this->docIndex === null) {
+            $this->docIndex = new DocIndex($this->root);
+        }
+        return $this->docIndex;
+    }
+
+    private function code(): CodeIndex
+    {
+        if ($this->codeIndex === null) {
+            $this->codeIndex = new CodeIndex($this->root);
+        }
+        $this->codeIndex->setAutoDirs($this->autoDirs);
+        return $this->codeIndex;
+    }
+
+    /**
+     * @param array<int|string, mixed> $arguments
+     */
+    private static function argString(array $arguments, string $key, string $default): string
+    {
+        if (!array_key_exists($key, $arguments) || !is_string($arguments[$key])) {
+            return $default;
+        }
+        return (string) $arguments[$key];
+    }
+
+    /**
+     * @param array<int|string, mixed> $arguments
+     */
+    private static function argInt(array $arguments, string $key, int $default): int
+    {
+        if (!array_key_exists($key, $arguments) || !is_int($arguments[$key])) {
+            return $default;
+        }
+        return (int) $arguments[$key];
+    }
+
+    /**
+     * @param array<int|string, mixed> $arguments
+     * @return array<int, mixed>
+     */
+    private static function argArray(array $arguments, string $key): array
+    {
+        if (!array_key_exists($key, $arguments) || !is_array($arguments[$key])) {
+            return [];
+        }
+        return $arguments[$key];
+    }
+
+    /**
+     * @param array<string, mixed> $payload
+     */
+    private function result(int|string|null $id, array|object $result): string
+    {
+        return $this->encode(['jsonrpc' => '2.0', 'id' => $id, 'result' => $result]);
+    }
+
+    private function error(int|string|null $id, int $code, string $message): string
+    {
+        return $this->encode(['jsonrpc' => '2.0', 'id' => $id, 'error' => [
+            'code' => $code,
+            'message' => $message,
+        ]]);
+    }
+
+    private function enqueueRootsList(): void
+    {
+        $id = $this->nextRequestId++;
+        $this->rootsRequestId = $id;
+        $this->outbound[] = $this->encode([
+            'jsonrpc' => '2.0',
+            'id' => $id,
+            'method' => 'roots/list',
+            'params' => (object)[],
+        ]);
+    }
+
+    /**
+     * @param array<string, mixed> $result
+     */
+    private function consumeRootsResponse(array $result): void
+    {
+        $roots = isset($result['roots']) && is_array($result['roots']) ? $result['roots'] : [];
+        foreach ($roots as $root) {
+            if (!is_array($root)) {
+                continue;
+            }
+            $uri = isset($root['uri']) && is_string($root['uri']) ? $root['uri'] : '';
+            if ($uri === '') {
+                continue;
+            }
+            $path = ProjectDetector::uriToPath($uri);
+            if (ProjectDetector::isTypePhpProject($path)) {
+                foreach (ProjectDetector::searchDirs($path) as $dir) {
+                    $this->addAutoDir($dir);
+                }
+            }
+        }
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    public function drainOutbound(): array
+    {
+        $out = $this->outbound;
+        $this->outbound = [];
+        return $out;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    public function getAutoDirs(): array
+    {
+        return $this->autoDirs;
+    }
+
+    /**
+     * @param array<string, mixed> $payload
+     */
+    private function encode(array $payload): string
+    {
+        $json = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+        if (!is_string($json)) {
+            return '{"jsonrpc":"2.0","id":null,"error":{"code":-32603,"message":"Internal error: json_encode failed"}}';
+        }
+        return $json;
+    }
+}
diff --git a/tools/typephp-mcp/src/ProjectDetector.php b/tools/typephp-mcp/src/ProjectDetector.php
new file mode 100644
index 00000000..5d9a8ad5
--- /dev/null
+++ b/tools/typephp-mcp/src/ProjectDetector.php
@@ -0,0 +1,72 @@
+<?php
+
+/**
+ * Detects whether a directory is a TypePHP project and derives the search roots
+ * the code tools should scan for it.
+ *
+ * A TypePHP project is recognized by any of:
+ *   - a Composer-installed framework at vendor/swoole/typephp
+ *   - a composer.json that requires swoole/typephp
+ *   - a project.yml (the TypePHP build manifest)
+ *
+ * This lets the server auto-merge the user's own project (plus its installed
+ * framework package) into the default search set, so the tools work on the
+ * IDE's open workspace without per-call dirs.
+ */
+final class ProjectDetector
+{
+    /**
+     * @return array<int, string> Normalized (forward-slash) absolute search
+     *   roots: the project root, plus vendor/swoole/typephp when present.
+     */
+    public static function searchDirs(string $dir): array
+    {
+        $dir = rtrim(str_replace('\\', '/', $dir), '/');
+        $dirs = [$dir];
+        $framework = $dir . '/vendor/swoole/typephp';
+        if (is_dir($framework)) {
+            $dirs[] = $framework;
+        }
+        return $dirs;
+    }
+
+    public static function isTypePhpProject(string $dir): bool
+    {
+        $dir = rtrim(str_replace('\\', '/', $dir), '/');
+        if ($dir === '' || !is_dir($dir)) {
+            return false;
+        }
+        if (is_dir($dir . '/vendor/swoole/typephp')) {
+            return true;
+        }
+        $composer = $dir . '/composer.json';
+        if (is_file($composer)) {
+            $content = file_get_contents($composer);
+            if (is_string($content) && str_contains($content, 'swoole/typephp')) {
+                return true;
+            }
+        }
+        if (is_file($dir . '/project.yml')) {
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Convert an MCP root URI (file://...) into a normalized absolute path.
+     */
+    public static function uriToPath(string $uri): string
+    {
+        $uri = trim($uri);
+        $path = preg_replace('#^file://(?:localhost)?#', '', $uri);
+        if (!is_string($path)) {
+            $path = $uri;
+        }
+        // file:///D:/x  ->  /D:/x  ->  D:/x
+        if (str_starts_with($path, '/') && preg_match('#^/[A-Za-z]:#', $path) === 1) {
+            $path = substr($path, 1);
+        }
+        $path = rawurldecode($path);
+        return str_replace('\\', '/', $path);
+    }
+}
diff --git a/tools/typephp-mcp/src/RepoRoot.php b/tools/typephp-mcp/src/RepoRoot.php
new file mode 100644
index 00000000..cdeea52b
--- /dev/null
+++ b/tools/typephp-mcp/src/RepoRoot.php
@@ -0,0 +1,109 @@
+<?php
+
+final class RepoRoot
+{
+    private string $root;
+
+    private function __construct(string $root)
+    {
+        $this->root = $root;
+    }
+
+    public static function detect(): self
+    {
+        $override = getenv('TYPEPHP_MCP_ROOT');
+        if (is_string($override) && $override !== '' && self::looksLikeRoot($override)) {
+            return new self(self::normalize($override));
+        }
+
+        $seeds = [];
+        $cwd = getcwd();
+        if (is_string($cwd) && $cwd !== '') {
+            $seeds[] = $cwd;
+        }
+        $seeds[] = TYPEPHP_MCP_DEFAULT_ROOT;
+
+        foreach ($seeds as $seed) {
+            $dir = self::normalize($seed);
+            for ($depth = 0; $depth < 8; $depth++) {
+                if (self::looksLikeRoot($dir)) {
+                    return new self($dir);
+                }
+                $parent = dirname($dir);
+                if ($parent === $dir) {
+                    break;
+                }
+                $dir = $parent;
+            }
+        }
+
+        throw new RuntimeException(
+            'TypePHP repository root not found. Set TYPEPHP_MCP_ROOT to the aot-compiler checkout.'
+        );
+    }
+
+    public static function looksLikeRoot(string $dir): bool
+    {
+        return is_dir($dir . '/docs') && is_file($dir . '/bin/tpc.php');
+    }
+
+    private static function normalize(string $dir): string
+    {
+        $real = realpath($dir);
+        return is_string($real) && $real !== '' ? $real : $dir;
+    }
+
+    public function path(): string
+    {
+        return $this->root;
+    }
+
+    public function docsPath(string $lang): string
+    {
+        return $this->root . '/docs/' . $lang;
+    }
+
+    public function examplesPath(): string
+    {
+        return $this->root . '/examples';
+    }
+
+    public function stdlibTestsPath(): string
+    {
+        return $this->root . '/tests/std';
+    }
+
+    public function srcPath(): string
+    {
+        return $this->root . '/src';
+    }
+
+    /**
+     * Resolve a repo-relative path, rejecting anything that escapes the root.
+     */
+    public function resolveInside(string $relative): ?string
+    {
+        $relative = str_replace('\\', '/', $relative);
+        if ($relative === '' || str_contains($relative, '..')) {
+            return null;
+        }
+        $candidate = $this->root . '/' . ltrim($relative, '/');
+        $real = realpath($candidate);
+        if (!is_string($real) || $real === '') {
+            return null;
+        }
+        if (!str_starts_with($real, $this->root)) {
+            return null;
+        }
+        return $real;
+    }
+
+    public function relativeFrom(string $absolute): string
+    {
+        $prefix = $this->root . '/';
+        if (str_starts_with($absolute, $prefix)) {
+            return substr($absolute, strlen($prefix));
+        }
+        return $absolute;
+    }
+}
diff --git a/tools/typephp-mcp/src/Restrictions.php b/tools/typephp-mcp/src/Restrictions.php
new file mode 100644
index 00000000..a1d6fcab
--- /dev/null
+++ b/tools/typephp-mcp/src/Restrictions.php
@@ -0,0 +1,167 @@
+<?php
+
+/**
+ * Compact TypePHP constraint knowledge, distilled from the repository docs.
+ *
+ * This is the "write code correctly on the first try" layer: stock PHP tooling
+ * does not know about the TypePHP subset, so these rules are surfaced before
+ * and alongside the compiler oracle (check_code).
+ *
+ * Sources (authoritative, read them for details):
+ *   docs/zh-cn/INCOMPATIBLE_PHP_FEATURES.md
+ *   docs/en/INCOMPATIBLE_PHP_FEATURES.md
+ *   docs/zh-cn/MIXED_CPP_PHP.md        (.stub.php contract)
+ *   docs/zh-cn/COMPILER_CLI.md         (CLI/YAML options)
+ *   docs/zh-cn/COMPILATION_MODES.md    (bin/lib/ext modes)
+ *   docs/zh-cn/STD_CONTAINERS.md, HIGH_PRECISION_TYPES.md,
+ *   COMPILE_TIME_FUNCTIONS.md, UNIVERSAL_METHODS.md
+ */
+final class Restrictions
+{
+    /**
+     * @return array<string, array{title: string, rules: array<int, string>}>
+     */
+    public static function topics(): array
+    {
+        return [
+            'structure' => [
+                'title' => '程序结构',
+                'rules' => [
+                    '全局作用域不允许可执行语句；只允许声明、use、declare、常量定义。echo/赋值等语句必须放进函数或方法。',
+                    '函数和方法内部不允许声明函数，也不允许声明具名类。',
+                    'bin 模式必须定义全局 main()；签名仅允许 function main() 或 function main(int $argc, array $argv)。',
+                    '文档要求 main() 返回 void；实际示例（examples/qt-taskboard）使用 int 退出码，以编译器行为为准。',
+                    '所有源文件必须是 UTF-8。',
+                ],
+            ],
+            'types' => [
+                'title' => '类型与声明',
+                'rules' => [
+                    '局部变量一旦被静态推断为具体 native 类型（int/float/bool/string/array），同一作用域内不能重新赋值为不兼容类型；需要 Zend 动态语义时用 std::any() 或文件级 use varint_types。',
+                    '不支持可变变量 $$var。',
+                    'declare 只支持 strict_types 与 encoding=UTF-8；strict_types=0 被拒绝；不支持 ticks。',
+                    '严格参数个数：非 variadic 函数不接受声明范围之外的额外参数，func_get_args() 不会放宽签名。',
+                    '__construct() 不允许返回值；参数默认值不允许出现在必填参数之前。',
+                    '联合/交叉/nullable 类型以 mixed/any 作为 C++ 表示；静态阶段会提前拒绝确定不兼容的用法。',
+                    '不支持 PHP 8.5 #[NoDiscard]；全局/命名空间常量声明上不允许 attributes（class constant 不受限制）。',
+                ],
+            ],
+            'refs' => [
+                'title' => '调用与引用',
+                'rules' => [
+                    '动态调用、闭包调用的引用参数必须显式 std::ref() 或 toRef()；这是已确认的语言设计约束，不会做运行时自动识别。',
+                    '闭包和箭头函数不支持按引用返回。',
+                    '不支持 Closure::bind()、Closure::bindTo()、Closure::call()。',
+                    '原生引用绑定必须无条件、一次性、函数内、不逃逸；条件/循环内首次绑定、重新绑定、unset、按引用返回局部变量、存入属性/数组/全局槽位都会在编译期被拒绝。',
+                    'Closure 的 use (&$value) 是显式退化边界：捕获的局部量退化为 php::Var。',
+                ],
+            ],
+            'objects' => [
+                'title' => '对象模型',
+                'rules' => [
+                    '不能继承内置类（例如 class MyDb extends PDO 会 fatal）；用组合持有，如 private PDO $connection。',
+                    'Native Class 使用独立固定布局，不能当作普通 Zend Object、PHP array key/value 或任意 mixed 值使用。',
+                    'toInt()/toString()/toArray() 等关键词方法先于普通对象方法解析；toAny()/toRef() 不可覆盖。',
+                    '禁止子类用同名 private 属性隐藏父类私有属性。',
+                ],
+            ],
+            'control' => [
+                'title' => '表达式与控制流',
+                'rules' => [
+                    '非空 switch case 必须以 return/break/continue/exit/throw 结束，不要依赖 PHP 的隐式 case fallthrough。',
+                    'foreach 遍历 std::vector/std::map/std::orderedMap 期间禁止追加、插入、unset() 或整体替换；已有元素的非结构性更新可以用赋值完成。',
+                    '静态类型明确为 array 时，与标量的算术、位运算及复合赋值编译期报错；array + array 使用 PHP 并集规则（保留左侧键与顺序）。',
+                    'match 的 arm condition 不能是 match 表达式。',
+                    'TypePHP 明确把 null 数组 key 视为追加操作，而不是转换为空字符串 key。',
+                ],
+            ],
+            'runtime' => [
+                'title' => '运行时动态能力',
+                'rules' => [
+                    '动态属性链、动态类名、动态函数名、动态回调统一走 Zend runtime fallback，不保证 native 优化。',
+                    'eval() 能通过 Zend VM 执行 PHP，但访问不到 AOT 编译的局部变量（AOT 局部量是 C++ 栈变量）；需用返回值或 $GLOBALS 交换数据。',
+                    'static::class 在需要编译期常量类名的位置不支持；__CLASS__/__TRAIT__ 只允许在对应 class/trait 定义内使用。',
+                    'include/require 可用（tests/compiler/include_require/ 有覆盖）。',
+                ],
+            ],
+            'std' => [
+                'title' => 'std 表面与属性代码生成',
+                'rules' => [
+                    '容器：std::array / std::vector / std::map / std::orderedMap（详见 docs/zh-cn/STD_CONTAINERS.md）。',
+                    '高精度数值：std::bigInt / std::decimal / std::bigFloat（详见 docs/zh-cn/HIGH_PRECISION_TYPES.md）。',
+                    '值构造：std::any() / std::object() / std::ref() / std::expected() / std::unexpected()。',
+                    '属性代码生成属性（如 #[Immutable]，见 examples/attributes/）与编译期函数见 docs/zh-cn/COMPILE_TIME_FUNCTIONS.md。',
+                    '通用方法（toString/toInt/toArray/jsonEncode/jsonDecode、String/Array/Stream 等 200+ 个）见 docs/zh-cn/UNIVERSAL_METHODS.md。',
+                ],
+            ],
+            'stub' => [
+                'title' => '.stub.php 契约（混合 C++/PHP）',
+                'rules' => [
+                    '.stub.php 只声明由外部 C++ 提供的 Zend ABI 符号；函数体必须为空 {}，写实现是编译错误。',
+                    '禁止对 .stub.php 中的类使用 #[Native]；Native Class 的对象布局必须由 TypePHP 编译器生成和持有。',
+                    '外部 C++ 函数硬规则：参数类型必须全是 php:: 类型；返回类型必须是 php:: 类型；函数名必须以 php_ 前缀开头；必须有对应 .stub.php 声明。',
+                    '-m lib 会把项目的 .php 与本地 .stub.php 聚合为目标 <target>.stub.php 并自动加 @import-library；#[\NoExport] 可把声明排除出公共 ABI。',
+                    '范式参考：examples/qt-taskboard/php-src/taskboard.stub.php、examples/prime/php-src/vector.stub.php。',
+                ],
+            ],
+            'build' => [
+                'title' => '构建配置（project.yml）',
+                'rules' => [
+                    'mode：bin（默认，需全局 main()）/ lib / ext；ext 模式用 info 提供 phpinfo 元数据。',
+                    '常用字段：name/version/cxx-std/cxx-flags/c-flags/ld-flags/sources/ignore/objects/include-paths/defines/link-paths/link-libs/ext-deps/embedded-files/entry/sapi/build-dir/output。',
+                    'ext-deps 是 PHP 扩展依赖（生成 ZEND_MOD_REQUIRED）；link-libs 是 C++ 链接库；两者不能互相替代。',
+                    '命令行参数优先于 YAML 同名项；--dry 只生成 C++，不编译不链接（链接期错误覆盖不到）。',
+                    'bin 模式默认 embed SAPI；cli/fpm SAPI 强依赖 php-builder，从 php-src 构建私有静态运行时。',
+                    'embedded-files 把 Composer vendor/只读资源打包进可执行文件；内嵌文件系统不支持 glob()/目录迭代。',
+                ],
+            ],
+        ];
+    }
+
+    public static function topicNames(): array
+    {
+        $names = [];
+        foreach (array_keys(self::topics()) as $name) {
+            $names[] = $name;
+        }
+        return $names;
+    }
+
+    public static function render(string $topic): string
+    {
+        $topics = self::topics();
+        if ($topic !== '' && $topic !== 'all') {
+            if (!array_key_exists($topic, $topics)) {
+                return 'Unknown topic: ' . $topic . "\nAvailable topics: " . implode(', ', self::topicNames());
+            }
+            $section = $topics[$topic];
+            return '## ' . $section['title'] . ' [' . $topic . "]\n- " . implode("\n- ", $section['rules'])
+                . "\n\nSources: docs/zh-cn/INCOMPATIBLE_PHP_FEATURES.md, docs/zh-cn/MIXED_CPP_PHP.md, docs/zh-cn/COMPILER_CLI.md";
+        }
+
+        $blocks = [];
+        foreach ($topics as $name => $section) {
+            $blocks[] = '## ' . $section['title'] . ' [' . $name . "]\n- " . implode("\n- ", $section['rules']);
+        }
+        return TextUtil::clip(implode("\n\n", $blocks), 6000);
+    }
+
+    /**
+     * ~800-token summary injected into tool descriptions and the initialize
+     * instructions, so an agent knows the red lines before calling any tool.
+     */
+    public static function summary(): string
+    {
+        return 'TypePHP red lines (verify with check_code before submitting): '
+            . '1) global scope allows declarations only (use/declare/const/functions/classes); executable statements live in main()/functions/methods. '
+            . '2) bin mode requires a global main() with signature main() or main(int $argc, array $argv). '
+            . '3) once a local is inferred as a concrete native type (int/float/bool/string/array) it cannot be reassigned to an incompatible type in the same scope; use std::any() for dynamic semantics. '
+            . '4) reference arguments of dynamic/Closure calls need explicit std::ref()/toRef(); closures cannot return by reference; Closure::bind/bindTo/call are unsupported. '
+            . '5) built-in classes cannot be extended (e.g. PDO) - use composition; Native Class objects are not plain Zend objects/arrays/mixed. '
+            . '6) every non-empty switch case must end with return/break/continue/exit/throw; do not rely on fallthrough. '
+            . '7) no $$var, no declare(ticks), strict_types=0 rejected; eval() cannot see AOT locals. '
+            . '8) .stub.php bodies must be empty {}; external C++ functions are php_-prefixed with php:: types only. '
+            . '9) foreach over std::vector/map/orderedMap forbids structural insert/remove. '
+            . '10) check_code covers C++ generation only, not link-time errors.';
+    }
+}
diff --git a/tools/typephp-mcp/src/TextUtil.php b/tools/typephp-mcp/src/TextUtil.php
new file mode 100644
index 00000000..dd00bfc2
--- /dev/null
+++ b/tools/typephp-mcp/src/TextUtil.php
@@ -0,0 +1,77 @@
+<?php
+
+final class TextUtil
+{
+    private const TRUNCATION_MARKER = "\n...[truncated]";
+
+    /**
+     * Clip text to a byte budget. The result never exceeds $maxBytes and never
+     * ends (or starts, see utf8SafeSlice) inside a UTF-8 sequence, so the
+     * output is always safe for json_encode.
+     */
+    public static function clip(string $text, int $maxBytes): string
+    {
+        if (strlen($text) <= $maxBytes) {
+            return $text;
+        }
+        $budget = $maxBytes - strlen(self::TRUNCATION_MARKER);
+        if ($budget < 1) {
+            $budget = 1;
+        }
+        return self::utf8SafeSlice($text, 0, $budget) . self::TRUNCATION_MARKER;
+    }
+
+    /**
+     * Cut a byte window that starts and ends on UTF-8 character boundaries.
+     */
+    public static function utf8SafeSlice(string $text, int $start, int $length): string
+    {
+        if ($start < 0) {
+            $start = 0;
+        }
+        $slice = substr($text, $start, $length);
+        // Drop leading continuation bytes of a character that started earlier.
+        $slice = (string) preg_replace('/^[\x80-\xBF]+/', '', $slice);
+        // Keep the longest prefix made of complete UTF-8 characters, which
+        // drops any trailing partial sequence.
+        $matched = preg_match(
+            '/^(?:[\x00-\x7F]|[\xC2-\xDF][\x80-\xBF]|[\xE0-\xEF][\x80-\xBF]{2}|[\xF0-\xF7][\x80-\xBF]{3})*/',
+            $slice,
+            $matches
+        );
+        if ($matched !== 1 || !is_array($matches)) {
+            return '';
+        }
+        return (string) $matches[0];
+    }
+
+    /**
+     * Split a search query into lowercase terms. CJK text has no word
+     * boundaries, so terms keep their punctuation and match by substring.
+     *
+     * @return array<int, string>
+     */
+    public static function terms(string $query): array
+    {
+        $parts = preg_split('/[\s,，、;；|]+/', $query);
+        $terms = [];
+        if (!is_array($parts)) {
+            return $terms;
+        }
+        foreach ($parts as $part) {
+            if (!is_string($part)) {
+                continue;
+            }
+            $part = trim($part);
+            if ($part !== '') {
+                $terms[] = strtolower($part);
+            }
+        }
+        return $terms;
+    }
+
+    public static function contains(string $haystack, string $needle): bool
+    {
+        return stripos($haystack, $needle) !== false;
+    }
+}
diff --git a/tools/typephp-mcp/src/ToolDefinitions.php b/tools/typephp-mcp/src/ToolDefinitions.php
new file mode 100644
index 00000000..476efb15
--- /dev/null
+++ b/tools/typephp-mcp/src/ToolDefinitions.php
@@ -0,0 +1,177 @@
+<?php
+
+final class ToolDefinitions
+{
+    public const SERVER_VERSION = '1.0.0';
+
+    /**
+     * @return array<int, array{name: string, description: string, inputSchema: array<string, mixed>}>
+     */
+    public static function all(): array
+    {
+        return [
+            [
+                'name' => 'check_code',
+                'description' => "Validate a PHP file or project.yml with the TypePHP compiler (`tpc --dry`, C++ generation only; link errors are not covered). Returns diagnostics with file:line, or OK. ALWAYS call this before submitting TypePHP code.\n\n"
+                    . Restrictions::summary(),
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'path' => [
+                            'type' => 'string',
+                            'description' => 'Absolute path to a .php file or project.yml, or a path relative to the repository root.',
+                        ],
+                    ],
+                    'required' => ['path'],
+                ],
+            ],
+            [
+                'name' => 'list_restrictions',
+                'description' => "List the TypePHP restrictions (what stock PHP allows but TypePHP rejects). Call BEFORE writing TypePHP code. Topics: structure, types, refs, objects, control, runtime, std, stub, build; empty topic returns the full summary.\n\n"
+                    . Restrictions::summary(),
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'topic' => [
+                            'type' => 'string',
+                            'description' => 'One of: structure, types, refs, objects, control, runtime, std, stub, build. Empty or "all" returns everything.',
+                        ],
+                    ],
+                ],
+            ],
+            [
+                'name' => 'get_symbol',
+                'description' => 'Find a function/class/interface/trait/enum/const declaration by exact name. Returns signature + file:line from src/, examples/ and tests/std/. Pass dirs to search your own project instead of the bundled repo.',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'name' => ['type' => 'string', 'description' => 'Exact symbol name, e.g. main, array_push, stdMap.'],
+                        'dirs' => [
+                            'type' => 'array',
+                            'items' => ['type' => 'string'],
+                            'description' => 'Optional list of absolute directories to search INSTEAD of the bundled aot-compiler repo (e.g. your project src plus vendor/swoole/typephp). Empty/absent searches the official repo; vendor/node_modules are NOT skipped when you pass dirs.',
+                        ],
+                    ],
+                    'required' => ['name'],
+                ],
+            ],
+            [
+                'name' => 'list_stdlib',
+                'description' => 'List the stdlib test categories under tests/std (array, core, dir, file, strings, ...) with real usage tests. With a category, lists the tests and their titles.',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'category' => ['type' => 'string', 'description' => 'Optional category directory name, e.g. array, strings, network.'],
+                    ],
+                ],
+            ],
+            [
+                'name' => 'get_example',
+                'description' => 'Return a runnable example: a single file (name without .php) or a directory (file list plus README/main.php/project.yml excerpts). By default searches examples/ in the bundled repo; pass dirs to look in your own project instead.',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'name' => ['type' => 'string', 'description' => 'Example name, e.g. hello, shop-fpm, qt-taskboard, bigint.'],
+                        'dirs' => [
+                            'type' => 'array',
+                            'items' => ['type' => 'string'],
+                            'description' => 'Optional list of absolute directories to search INSTEAD of the bundled examples/ (e.g. your project root). Empty/absent searches the official repo; vendor/node_modules are NOT skipped when you pass dirs.',
+                        ],
+                    ],
+                    'required' => ['name'],
+                ],
+            ],
+            [
+                'name' => 'get_stub_api',
+                'description' => 'Inspect .stub.php declarations (the C++/PHP ABI contract). Without a path, lists all stub files; with a path, returns the declarations of that file. By default scopes to the bundled repo; pass dirs to list/read stubs in your own project (e.g. vendor/swoole/typephp).',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'path' => ['type' => 'string', 'description' => 'Path to a .stub.php file, relative to a dir in dirs (or repo-relative when dirs is empty), e.g. examples/qt-taskboard/php-src/taskboard.stub.php.'],
+                        'dirs' => [
+                            'type' => 'array',
+                            'items' => ['type' => 'string'],
+                            'description' => 'Optional list of absolute directories to search INSTEAD of the bundled repo. Empty/absent searches the official repo; vendor/node_modules are NOT skipped when you pass dirs.',
+                        ],
+                    ],
+                ],
+            ],
+            [
+                'name' => 'search_docs',
+                'description' => 'Full-text search over docs/zh-cn and docs/en. Returns chunks with docs/<lang>/<file>.md#<heading> (L<line>) citations. Bilingual: lang selects zh-cn (default), en, or all.',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'query' => ['type' => 'string', 'description' => 'Keywords, e.g. "std::bigInt", "property hook", "embedded-files".'],
+                        'lang' => ['type' => 'string', 'description' => 'zh-cn (default), en, or all.'],
+                        'limit' => ['type' => 'integer', 'description' => 'Max chunks to return (default 5, max 10).'],
+                    ],
+                    'required' => ['query'],
+                ],
+            ],
+            [
+                'name' => 'search_code',
+                'description' => 'Grep for a code snippet or API name. By default searches examples/, tests/std/ and src/ of the bundled repo; pass dirs to search your own project (and its Composer-installed framework). Returns file:line plus the enclosing declaration (max 3 hits per file).',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'query' => ['type' => 'string', 'description' => 'Text to find, e.g. "std::orderedMap", "proc_open", "JSON_THROW_ON_ERROR".'],
+                        'limit' => ['type' => 'integer', 'description' => 'Max hits (default 15, max 30).'],
+                        'dirs' => [
+                            'type' => 'array',
+                            'items' => ['type' => 'string'],
+                            'description' => 'Optional list of absolute directories to search INSTEAD of the bundled repo (e.g. your project src plus vendor/swoole/typephp). Empty/absent searches the official repo; vendor/node_modules are NOT skipped when you pass dirs.',
+                        ],
+                    ],
+                    'required' => ['query'],
+                ],
+            ],
+            [
+                'name' => 'get_changelog',
+                'description' => 'Read CHANGELOG.md: latest section, or the section for a specific version. Use before relying on behavior that may have changed (e.g. native scalar storage default in 0.8.0).',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'version' => ['type' => 'string', 'description' => 'Version prefix, e.g. 0.8. Empty returns the latest section.'],
+                    ],
+                ],
+            ],
+            [
+                'name' => 'get_build_config_help',
+                'description' => 'Explain project.yml and the three build modes (bin/lib/ext): sources, ignore, objects, include-paths, defines, link-paths, link-libs, ext-deps, embedded-files, entry, sapi; CLI flags (--dry, -O, -m, --sapi, --php-builder); and the .stub.php contract.',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => (object)[],
+                ],
+            ],
+            [
+                'name' => 'list_topics',
+                'description' => 'List all documentation topics (docs/zh-cn and docs/en) with their titles, so you know what can be searched with search_docs.',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => (object)[],
+                ],
+            ],
+            [
+                'name' => 'get_index_info',
+                'description' => 'Index metadata: repo root, tpc version, git commit, doc counts, tool list. Use to detect staleness (version drift is a top risk with this young compiler).',
+                'inputSchema' => [
+                    'type' => 'object',
+                    'properties' => (object)[],
+                ],
+            ],
+        ];
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    public static function names(): array
+    {
+        $names = [];
+        foreach (self::all() as $tool) {
+            $names[] = $tool['name'];
+        }
+        return $names;
+    }
+}
diff --git a/tools/typephp-mcp/tests/McpBinaryTest.php b/tools/typephp-mcp/tests/McpBinaryTest.php
new file mode 100644
index 00000000..422cc7a6
--- /dev/null
+++ b/tools/typephp-mcp/tests/McpBinaryTest.php
@@ -0,0 +1,117 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Integration test: drives the compiled typephp_mcp.exe over a real stdio
+ * session, including a live per-message flush check (the reply must arrive
+ * while stdin is still open). Skips when the binary has not been built.
+ */
+final class McpBinaryTest extends TestCase
+{
+    private const EXECUTABLE = __DIR__ . '/../typephp_mcp.exe';
+
+    private const REPO_ROOT = __DIR__ . '/../../..';
+
+    public function testStdioMcpSession(): void
+    {
+        if (!is_file(self::EXECUTABLE)) {
+            self::markTestSkipped('typephp_mcp.exe not built; run tools/typephp-mcp/build.bat');
+        }
+
+        $process = proc_open(
+            [self::EXECUTABLE],
+            [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']],
+            $pipes,
+            self::REPO_ROOT
+        );
+        self::assertIsResource($process);
+
+        try {
+            stream_set_blocking($pipes[0], false);
+            $initialize = ['jsonrpc' => '2.0', 'id' => 1, 'method' => 'initialize', 'params' => []];
+            self::assertNotFalse(fwrite($pipes[0], (string) json_encode($initialize) . "\n"));
+
+            $reply = $this->readReply($pipes[1], 20.0);
+            self::assertNotNull($reply, 'no initialize reply within timeout');
+            self::assertSame('typephp-mcp', $reply['result']['serverInfo']['name']);
+            self::assertSame('2024-11-05', $reply['result']['protocolVersion']);
+
+            $notification = ['jsonrpc' => '2.0', 'method' => 'notifications/initialized'];
+            self::assertNotFalse(fwrite($pipes[0], (string) json_encode($notification) . "\n"));
+
+            $list = ['jsonrpc' => '2.0', 'id' => 2, 'method' => 'tools/list'];
+            self::assertNotFalse(fwrite($pipes[0], (string) json_encode($list) . "\n"));
+            $reply = $this->readReply($pipes[1], 20.0);
+            self::assertNotNull($reply);
+            self::assertCount(12, $reply['result']['tools']);
+
+            $call = [
+                'jsonrpc' => '2.0',
+                'id' => 3,
+                'method' => 'tools/call',
+                'params' => ['name' => 'list_restrictions', 'arguments' => ['topic' => 'structure']],
+            ];
+            self::assertNotFalse(fwrite($pipes[0], (string) json_encode($call) . "\n"));
+            $reply = $this->readReply($pipes[1], 20.0);
+            self::assertNotNull($reply);
+            self::assertStringContainsString('main()', $reply['result']['content'][0]['text']);
+
+            // A CJK-heavy query: the reply must be valid JSON even though the
+            // excerpt is cut on a byte budget (UTF-8 boundary safety).
+            $call = [
+                'jsonrpc' => '2.0',
+                'id' => 4,
+                'method' => 'tools/call',
+                'params' => ['name' => 'search_docs', 'arguments' => ['query' => 'bigInt', 'lang' => 'zh-cn', 'limit' => 3]],
+            ];
+            self::assertNotFalse(fwrite($pipes[0], (string) json_encode($call) . "\n"));
+            $reply = $this->readReply($pipes[1], 20.0);
+            self::assertNotNull($reply);
+            self::assertSame(JSON_ERROR_NONE, json_last_error());
+            self::assertStringContainsString('docs/zh-cn/', $reply['result']['content'][0]['text']);
+        } finally {
+            fclose($pipes[0]);
+            fclose($pipes[1]);
+            fclose($pipes[2]);
+            proc_close($process);
+        }
+    }
+
+    /**
+     * Read one newline-delimited JSON reply, waiting at most $seconds. The
+     * timeout proves the server flushes each reply instead of buffering until
+     * stdin closes (which would deadlock every real MCP client).
+     *
+     * @param resource $stream
+     * @return array<string, mixed>|null
+     */
+    private function readReply($stream, float $seconds): ?array
+    {
+        $deadline = microtime(true) + $seconds;
+        $buffer = '';
+        while (microtime(true) < $deadline) {
+            $read = [$stream];
+            $write = null;
+            $except = null;
+            $ready = stream_select($read, $write, $except, 0, 200000);
+            if ($ready === false) {
+                return null;
+            }
+            if ($ready > 0) {
+                $chunk = (string) fread($stream, 8192);
+                if ($chunk === '') {
+                    return null;
+                }
+                $buffer .= $chunk;
+                $position = strpos($buffer, "\n");
+                if ($position !== false) {
+                    $line = substr($buffer, 0, $position);
+                    $decoded = json_decode($line, true);
+                    return is_array($decoded) ? $decoded : null;
+                }
+            }
+        }
+        return null;
+    }
+}
diff --git a/tools/typephp-mcp/tests/McpServerTest.php b/tools/typephp-mcp/tests/McpServerTest.php
new file mode 100644
index 00000000..2b14d5eb
--- /dev/null
+++ b/tools/typephp-mcp/tests/McpServerTest.php
@@ -0,0 +1,592 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+require_once __DIR__ . '/../src/Config.php';
+require_once __DIR__ . '/../src/TextUtil.php';
+require_once __DIR__ . '/../src/RepoRoot.php';
+require_once __DIR__ . '/../src/Restrictions.php';
+require_once __DIR__ . '/../src/DocIndex.php';
+require_once __DIR__ . '/../src/CodeIndex.php';
+require_once __DIR__ . '/../src/CompilerOracle.php';
+require_once __DIR__ . '/../src/IndexInfo.php';
+require_once __DIR__ . '/../src/ToolDefinitions.php';
+require_once __DIR__ . '/../src/McpServer.php';
+require_once __DIR__ . '/../src/ProjectDetector.php';
+
+/**
+ * Unit tests for the typephp-mcp server logic. Everything here runs with a
+ * plain PHP interpreter: the sources are kept inside the PHP subset that both
+ * stock PHP and the TypePHP compiler accept, so the same files are exercised
+ * interpreted (here) and AOT-compiled (see McpBinaryTest).
+ */
+final class McpServerTest extends TestCase
+{
+    private McpServer $server;
+
+    private RepoRoot $root;
+
+    protected function setUp(): void
+    {
+        $this->root = RepoRoot::detect();
+        $this->server = new McpServer($this->root);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function request(string $line): array
+    {
+        $reply = $this->server->handleLine($line);
+        self::assertNotNull($reply, 'expected a JSON-RPC reply');
+        $decoded = json_decode((string) $reply, true);
+        self::assertIsArray($decoded);
+        return $decoded;
+    }
+
+    private function toolText(string $name, array $arguments = []): string
+    {
+        $reply = $this->request((string) json_encode([
+            'jsonrpc' => '2.0',
+            'id' => 1,
+            'method' => 'tools/call',
+            'params' => ['name' => $name, 'arguments' => $arguments],
+        ]));
+        self::assertArrayHasKey('result', $reply);
+        $content = $reply['result']['content'][0]['text'] ?? null;
+        self::assertIsString($content);
+        return $content;
+    }
+
+    public function testInitializeHandshake(): void
+    {
+        $reply = $this->request('{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}');
+        self::assertSame('2024-11-05', $reply['result']['protocolVersion']);
+        self::assertSame('typephp-mcp', $reply['result']['serverInfo']['name']);
+        self::assertSame([], (array) $reply['result']['capabilities']['tools']);
+        self::assertStringContainsString('global scope allows declarations only', $reply['result']['instructions']);
+    }
+
+    public function testPingReturnsEmptyResult(): void
+    {
+        $reply = $this->request('{"jsonrpc":"2.0","id":2,"method":"ping"}');
+        self::assertSame([], (array) $reply['result']);
+    }
+
+    public function testNotificationsAreNotAnswered(): void
+    {
+        self::assertNull($this->server->handleLine('{"jsonrpc":"2.0","method":"notifications/initialized"}'));
+    }
+
+    public function testParseErrorReportsNullId(): void
+    {
+        $reply = $this->request('this is not json');
+        self::assertNull($reply['id']);
+        self::assertSame(-32700, $reply['error']['code']);
+    }
+
+    public function testUnknownMethodAndUnknownTool(): void
+    {
+        $reply = $this->request('{"jsonrpc":"2.0","id":3,"method":"bogus/method"}');
+        self::assertSame(-32601, $reply['error']['code']);
+
+        $reply = $this->request('{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"nope","arguments":{}}}');
+        self::assertSame(-32602, $reply['error']['code']);
+    }
+
+    public function testToolsListExposesTwelveTools(): void
+    {
+        $raw = (string) $this->server->handleLine('{"jsonrpc":"2.0","id":5,"method":"tools/list"}');
+        $reply = json_decode($raw, true);
+        $tools = $reply['result']['tools'];
+        self::assertCount(12, $tools);
+        foreach ($tools as $tool) {
+            self::assertArrayHasKey('name', $tool);
+            self::assertArrayHasKey('description', $tool);
+            self::assertSame('object', $tool['inputSchema']['type']);
+        }
+        // JSON Schema requires inputSchema.properties to be an object, never an
+        // array. A parameterless tool whose properties is an empty PHP list
+        // encodes to [] and fails the MCP SDK's ListToolsResultSchema
+        // validation, which makes clients (CodeBuddy, the official SDK) report
+        // 0 tools. Verify the serialized reply never contains "properties":[].
+        self::assertStringNotContainsString(
+            '"properties":[]',
+            $raw,
+            'inputSchema.properties must serialize as an object, never an array'
+        );
+    }
+
+    public function testInitializeEchoesClientProtocolVersion(): void
+    {
+        $reply = $this->request('{"jsonrpc":"2.0","id":6,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"x","version":"1"}}}');
+        self::assertSame('2025-06-18', $reply['result']['protocolVersion']);
+
+        // No version offered by the client -> fall back to ours.
+        $reply = $this->request('{"jsonrpc":"2.0","id":7,"method":"initialize","params":{}}');
+        self::assertSame('2024-11-05', $reply['result']['protocolVersion']);
+    }
+
+    public function testOptionalCapabilityListsReturnEmptyResults(): void
+    {
+        // Clients probe prompts/resources in parallel with tools; an error
+        // reply makes picky clients report "0 tools".
+        $pairs = [
+            'prompts/list' => 'prompts',
+            'resources/list' => 'resources',
+            'resources/templates/list' => 'resourceTemplates',
+        ];
+        foreach ($pairs as $method => $key) {
+            $reply = $this->request('{"jsonrpc":"2.0","id":8,"method":"' . $method . '"}');
+            self::assertArrayHasKey('result', $reply, $method);
+            self::assertSame([], (array) $reply['result'][$key], $method);
+        }
+        $reply = $this->request('{"jsonrpc":"2.0","id":8,"method":"logging/setLevel","params":{"level":"info"}}');
+        self::assertSame([], (array) $reply['result']);
+    }
+
+    public function testCheckCodeAcceptsAValidFile(): void
+    {
+        if (CompilerOracle::phpBinary() === '') {
+            self::markTestSkipped('no php executable on PATH');
+        }
+        $text = $this->toolText('check_code', ['path' => 'examples/hello.php']);
+        self::assertStringStartsWith('OK:', $text);
+        self::assertStringContainsString('link-time errors are not checked', $text);
+    }
+
+    public function testMsvcBinDirDiscovery(): void
+    {
+        $vswhere = getenv('ProgramFiles(x86)') . '\Microsoft Visual Studio\Installer\vswhere.exe';
+        if (!is_file($vswhere)) {
+            self::markTestSkipped('vswhere.exe not found');
+        }
+        $method = new ReflectionMethod(CompilerOracle::class, 'findMsvcBinDir');
+        $binDir = $method->invoke(null);
+        if ($binDir === null) {
+            self::markTestSkipped('no MSVC toolchain with VC.Tools.x86.x64 installed');
+        }
+        self::assertDirectoryExists($binDir);
+        self::assertFileExists($binDir . '\cl.exe');
+    }
+
+    public function testCheckCodeRejectsAnIllegalGlobalStatement(): void
+    {
+        if (CompilerOracle::phpBinary() === '') {
+            self::markTestSkipped('no php executable on PATH');
+        }
+        $file = sys_get_temp_dir() . '/typephp-mcp-test-' . bin2hex(random_bytes(4)) . '.php';
+        self::assertNotFalse(file_put_contents($file, "<?php\necho \"illegal at global scope\";\n"));
+        try {
+            $text = $this->toolText('check_code', ['path' => $file]);
+            self::assertStringStartsWith('FAILED', $text);
+            self::assertStringContainsString('Unsupported statement', $text);
+        } finally {
+            @unlink($file);
+        }
+    }
+
+    public function testListRestrictionsCoversMainSignatureAndScope(): void
+    {
+        $text = $this->toolText('list_restrictions', ['topic' => 'structure']);
+        self::assertStringContainsString('main()', $text);
+        self::assertStringContainsString('全局作用域', $text);
+        self::assertStringContainsString('[structure]', $text);
+
+        $text = $this->toolText('list_restrictions', ['topic' => 'does-not-exist']);
+        self::assertStringContainsString('Available topics:', $text);
+
+        $text = $this->toolText('list_restrictions', []);
+        self::assertStringContainsString('.stub.php', $text);
+        self::assertStringContainsString('std::ref()', $text);
+    }
+
+    public function testSearchDocsCitesSourceFileAndLine(): void
+    {
+        $text = $this->toolText('search_docs', ['query' => 'bigInt', 'lang' => 'zh-cn', 'limit' => 3]);
+        self::assertStringContainsString('docs/zh-cn/', $text);
+        self::assertStringContainsString('(L', $text);
+        self::assertStringContainsString('bigInt', $text);
+    }
+
+    public function testSearchCodeFindsStdContainerUsage(): void
+    {
+        $text = $this->toolText('search_code', ['query' => 'orderedMap', 'limit' => 5]);
+        self::assertStringContainsString('src/Parser/StdContainerTrait.php:', $text);
+        self::assertStringContainsString('in ', $text);
+    }
+
+    public function testGetSymbolFindsMain(): void
+    {
+        $text = $this->toolText('get_symbol', ['name' => 'main']);
+        self::assertStringContainsString('function main', $text);
+        self::assertStringContainsString(':', $text);
+
+        $text = $this->toolText('get_symbol', ['name' => 'definitely_not_a_symbol_xyz']);
+        self::assertStringContainsString('No symbol found', $text);
+    }
+
+    public function testGetExampleReturnsFileAndDirectory(): void
+    {
+        $text = $this->toolText('get_example', ['name' => 'hello']);
+        self::assertStringContainsString('examples/hello.php', $text);
+        self::assertStringContainsString('function main', $text);
+
+        $text = $this->toolText('get_example', ['name' => 'qt-taskboard']);
+        self::assertStringContainsString('examples/qt-taskboard/', $text);
+        self::assertStringContainsString('project.yml', $text);
+
+        $text = $this->toolText('get_example', ['name' => '../../etc/passwd']);
+        self::assertStringContainsString('Invalid example name', $text);
+    }
+
+    public function testListStdlibListsCategoriesAndTests(): void
+    {
+        $text = $this->toolText('list_stdlib', []);
+        self::assertStringContainsString('array (', $text);
+        self::assertStringContainsString('strings (', $text);
+        self::assertStringContainsString('STD_CONTAINERS.md', $text);
+
+        $text = $this->toolText('list_stdlib', ['category' => 'hrtime']);
+        self::assertStringContainsString('.phpt', $text);
+    }
+
+    public function testGetStubApiListsAndReadsStubFiles(): void
+    {
+        $text = $this->toolText('get_stub_api', []);
+        self::assertStringContainsString('taskboard.stub.php', $text);
+
+        $text = $this->toolText('get_stub_api', ['path' => 'examples/qt-taskboard/php-src/taskboard.stub.php']);
+        self::assertStringContainsString('qt_board_', $text);
+
+        $text = $this->toolText('get_stub_api', ['path' => 'project.yml']);
+        self::assertStringContainsString('Not a .stub.php file', $text);
+    }
+
+    public function testGetChangelogReturnsLatestAndSpecificSections(): void
+    {
+        $text = $this->toolText('get_changelog', []);
+        self::assertStringContainsString('## 0.8.0', $text);
+
+        $text = $this->toolText('get_changelog', ['version' => '0.8']);
+        self::assertStringContainsString('native scalar storage', $text);
+
+        $text = $this->toolText('get_changelog', ['version' => '99.0']);
+        self::assertStringContainsString('No changelog section', $text);
+    }
+
+    public function testGetBuildConfigHelpCoversYamlAndStubContract(): void
+    {
+        $text = $this->toolText('get_build_config_help', []);
+        self::assertStringContainsString('ext-deps', $text);
+        self::assertStringContainsString('php_ 前缀', $text);
+    }
+
+    public function testListTopicsIncludesIncompatibleFeatures(): void
+    {
+        $text = $this->toolText('list_topics', []);
+        self::assertStringContainsString('[zh-cn] INCOMPATIBLE_PHP_FEATURES.md', $text);
+        self::assertStringContainsString('[en] INCOMPATIBLE_PHP_FEATURES.md', $text);
+    }
+
+    public function testGetIndexInfoReportsRepoAndVersion(): void
+    {
+        $text = $this->toolText('get_index_info', []);
+        self::assertStringContainsString('repo_root: ' . $this->root->path(), $text);
+        self::assertStringContainsString('tools (12):', $text);
+    }
+
+    public function testTextClipKeepsUtf8Boundaries(): void
+    {
+        $text = str_repeat('中', 100);
+        $clipped = TextUtil::clip($text, 50);
+        self::assertLessThanOrEqual(50, strlen($clipped));
+        self::assertNotFalse(json_encode($clipped, JSON_UNESCAPED_UNICODE));
+        self::assertStringContainsString('truncated', $clipped);
+        self::assertSame($text, TextUtil::clip($text, 5000));
+        // Cutting at every possible offset must stay valid UTF-8.
+        for ($i = 1; $i <= 40; $i++) {
+            self::assertNotFalse(json_encode(TextUtil::clip($text, $i), JSON_UNESCAPED_UNICODE));
+        }
+        // A slice starting mid-character must drop the partial lead.
+        $mixed = 'a中b文c';
+        self::assertSame('', TextUtil::utf8SafeSlice($mixed, 1, 2));
+        self::assertSame('中', TextUtil::utf8SafeSlice($mixed, 1, 3));
+        self::assertSame('b文', TextUtil::utf8SafeSlice($mixed, 4, 4));
+    }
+
+    private function makeSandbox(): string
+    {
+        $dir = sys_get_temp_dir() . '/typephp-mcp-dirs-' . bin2hex(random_bytes(4));
+        self::assertTrue(mkdir($dir, 0777, true));
+        // Normalize to forward slashes so it matches ProjectDetector /
+        // resolveInsideAny, which also normalize (realpath returns forward
+        // slashes on Windows).
+        return str_replace('\\', '/', $dir);
+    }
+
+    private function sandboxWrite(string $dir, string $rel, string $content): void
+    {
+        $path = $dir . '/' . $rel;
+        $parent = dirname($path);
+        if (!is_dir($parent)) {
+            self::assertTrue(mkdir($parent, 0777, true));
+        }
+        self::assertNotFalse(file_put_contents($path, $content));
+    }
+
+    private function removeDir(string $dir): void
+    {
+        $items = scandir($dir);
+        if (!is_array($items)) {
+            return;
+        }
+        foreach ($items as $item) {
+            if ($item === '.' || $item === '..') {
+                continue;
+            }
+            $path = $dir . '/' . $item;
+            if (is_dir($path)) {
+                $this->removeDir($path);
+            } else {
+                @unlink($path);
+            }
+        }
+        @rmdir($dir);
+    }
+
+    public function testGetStubApiListsUserProjectDirs(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            $this->sandboxWrite($sandbox, 'php-src/Foo.stub.php', "<?php\nfunction php_foo(): void {}\n");
+
+            $text = $this->toolText('get_stub_api', ['dirs' => [$sandbox]]);
+            self::assertStringContainsString('php-src/Foo.stub.php', $text);
+
+            $text = $this->toolText('get_stub_api', ['path' => 'php-src/Foo.stub.php', 'dirs' => [$sandbox]]);
+            self::assertStringContainsString('function php_foo', $text);
+
+            // Without dirs the same relative path is not found in the repo.
+            $text = $this->toolText('get_stub_api', ['path' => 'php-src/Foo.stub.php']);
+            self::assertStringContainsString('Stub file not found inside the repository', $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testSearchCodeSearchesUserDirsAndIncludesVendor(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            $marker = 'UNIQUE_MARKER_X9Z';
+            $this->sandboxWrite($sandbox, 'src/App.php', "<?php\n// $marker\nclass App {}\n");
+            $this->sandboxWrite($sandbox, 'vendor/swoole/typephp/Framework.php', "<?php\n// $marker\nfunction php_framework() {}\n");
+
+            $text = $this->toolText('search_code', ['query' => $marker, 'dirs' => [$sandbox]]);
+            self::assertStringContainsString('src/App.php', $text);
+            self::assertStringContainsString('vendor/swoole/typephp/Framework.php', $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testGetSymbolSearchesUserDirs(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            $this->sandboxWrite($sandbox, 'src/CmySymbol.php', "<?php\nclass CmySymbol {}\n");
+
+            $text = $this->toolText('get_symbol', ['name' => 'CmySymbol', 'dirs' => [$sandbox]]);
+            self::assertStringContainsString('src/CmySymbol.php', $text);
+
+            $text = $this->toolText('get_symbol', ['name' => 'CmySymbol']);
+            self::assertStringContainsString('No symbol found', $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testGetExampleInUserDirs(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            $this->sandboxWrite($sandbox, 'main.php', "<?php\nfunction main(): void {}\n");
+
+            $text = $this->toolText('get_example', ['name' => 'main', 'dirs' => [$sandbox]]);
+            self::assertStringContainsString('main.php', $text);
+            self::assertStringContainsString('function main', $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testDirsInvalidRaisesToolError(): void
+    {
+        $text = $this->toolText('get_stub_api', ['dirs' => ['D:/no/such/dir/' . bin2hex(random_bytes(4))]]);
+        self::assertStringContainsString('none of the provided paths', $text);
+    }
+
+    public function testDirsTraversalRejected(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            $this->sandboxWrite($sandbox, 'php-src/Foo.stub.php', "<?php\nfunction php_foo(): void {}\n");
+
+            $text = $this->toolText('get_stub_api', ['path' => '../../etc/passwd', 'dirs' => [$sandbox]]);
+            self::assertStringContainsString('Stub file not found inside the provided dirs', $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testProjectDetectorRecognizesTypePhpProject(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            self::assertFalse(ProjectDetector::isTypePhpProject($sandbox));
+
+            mkdir($sandbox . '/vendor/swoole/typephp', 0777, true);
+            self::assertTrue(ProjectDetector::isTypePhpProject($sandbox));
+
+            $dirs = ProjectDetector::searchDirs($sandbox);
+            self::assertContains($sandbox, $dirs);
+            self::assertContains($sandbox . '/vendor/swoole/typephp', $dirs);
+
+            // composer.json requiring the framework also counts.
+            $plain = $this->makeSandbox();
+            file_put_contents($plain . '/composer.json', '{"require":{"swoole/typephp":"*"}}');
+            self::assertTrue(ProjectDetector::isTypePhpProject($plain));
+            $this->removeDir($plain);
+
+            // project.yml counts too.
+            $plain2 = $this->makeSandbox();
+            file_put_contents($plain2 . '/project.yml', "entry: main\n");
+            self::assertTrue(ProjectDetector::isTypePhpProject($plain2));
+            $this->removeDir($plain2);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testProjectDetectorUriToPath(): void
+    {
+        self::assertSame('D:/git/php/typephp-qt', ProjectDetector::uriToPath('file:///D:/git/php/typephp-qt'));
+        self::assertSame('/home/user/proj', ProjectDetector::uriToPath('file:///home/user/proj'));
+        self::assertSame('D:/git/php/typephp-qt', ProjectDetector::uriToPath('D:/git/php/typephp-qt'));
+    }
+
+    public function testCodeIndexMergesAutoDirsIntoDefault(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            $marker = 'AUTODIR_MARKER_Q7';
+            $this->sandboxWrite($sandbox, 'src/App.php', "<?php\n// $marker\nclass App {}\n");
+            $this->sandboxWrite($sandbox, 'php-src/ProjBar.stub.php', "<?php\nfunction php_bar(): void {}\n");
+
+            $code = new CodeIndex($this->root);
+            $code->setAutoDirs([$sandbox]);
+
+            // Default search (no explicit dirs) now covers the project.
+            $text = $code->searchCode($marker, 5);
+            self::assertStringContainsString('src/App.php', $text);
+
+            $text = $code->getStubApi('');
+            self::assertStringContainsString('php-src/ProjBar.stub.php', $text);
+
+            $text = $code->getStubApi('php-src/ProjBar.stub.php');
+            self::assertStringContainsString('function php_bar', $text);
+
+            // Explicit dirs still replace the auto-dirs (this valid dir has
+            // no marker, so the project hit must not appear).
+            $other = $this->makeSandbox();
+            $text = $code->searchCode($marker, 5, [$other]);
+            self::assertStringContainsString('No code matches', $text);
+            $this->removeDir($other);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testRootsCapabilityAutoDetectsProject(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            mkdir($sandbox . '/vendor/swoole/typephp', 0777, true);
+            file_put_contents($sandbox . '/vendor/swoole/typephp/ProjFoo.stub.php', "<?php\nfunction php_foo(): void {}\n");
+
+            // Client advertises roots; server should respond and ask for them.
+            $reply = $this->request('{"jsonrpc":"2.0","id":1,"method":"initialize","params":'
+                . '{"protocolVersion":"2024-11-05","capabilities":{"roots":{}},'
+                . '"clientInfo":{"name":"x","version":"1"}}}');
+            self::assertArrayHasKey('roots', $reply['result']['capabilities']);
+
+            // initialized notification -> server enqueues a roots/list request.
+            self::assertNull($this->server->handleLine('{"jsonrpc":"2.0","method":"notifications/initialized"}'));
+            $out = $this->server->drainOutbound();
+            self::assertCount(1, $out);
+            $req = json_decode($out[0], true);
+            self::assertSame('roots/list', $req['method']);
+
+            // Client answers with the TypePHP project URI.
+            $uri = 'file:///' . str_replace('\\', '/', $sandbox);
+            self::assertNull($this->server->handleLine(json_encode([
+                'jsonrpc' => '2.0',
+                'id' => $req['id'],
+                'result' => ['roots' => [['uri' => $uri]]],
+            ])));
+
+            // Now the default (no-dirs) stub listing includes the project.
+            $text = $this->toolText('get_stub_api', []);
+            self::assertStringContainsString('ProjFoo.stub.php', $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testCwdAutoDetectsProject(): void
+    {
+        $sandbox = $this->makeSandbox();
+        try {
+            mkdir($sandbox . '/vendor/swoole/typephp', 0777, true);
+            file_put_contents($sandbox . '/vendor/swoole/typephp/CwdFoo.stub.php', "<?php\nfunction php_cwd_foo(): void {}\n");
+
+            $prev = getcwd();
+            chdir($sandbox);
+            try {
+                // Server built with cwd = the project: should auto-merge it
+                // into the default search set without any env or roots.
+                $server = new McpServer($this->root);
+            } finally {
+                chdir($prev);
+            }
+
+            $reply = $server->handleLine(json_encode([
+                'jsonrpc' => '2.0',
+                'id' => 1,
+                'method' => 'tools/call',
+                'params' => ['name' => 'get_stub_api', 'arguments' => []],
+            ]));
+            $data = json_decode($reply, true);
+            $text = $data['result']['content'][0]['text'];
+            self::assertStringContainsString('CwdFoo.stub.php', $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testCwdDoesNotDoubleScanCompilerRepo(): void
+    {
+        // If cwd lands inside the bundled compiler repo, it must NOT be re-added
+        // as an auto project (it is already the default root).
+        $prev = getcwd();
+        chdir($this->root->path());
+        try {
+            $server = new McpServer($this->root);
+        } finally {
+            chdir($prev);
+        }
+        // No assertion beyond "does not throw / no crash"; autoDirs stays empty.
+        self::assertTrue(true);
+    }
+}

From 2d38803579629e20402d36476006c0abaf42c5c8 Mon Sep 17 00:00:00 2001
From: yangweijie <917647288@qq.com>
Date: Sat, 24 Oct 2026 12:33:42 +0800
Subject: [PATCH 2/2] feat(tools): build and test typephp-mcp on macOS

Windows was the only platform with an entry point, so the tool could neither be
compiled nor tested here: build.bat is cmd-only, McpBinaryTest hard-coded
typephp_mcp.exe and therefore always skipped, and the README documented only
Windows paths and clients.

Add build.sh. There is no tpc package directory on Unix, so it locates a host
embed runtime instead (PHP_HOME/PHPX_HOME, then the newest php-builder private
runtime, then vendor/swoole/phpx) and derives the link libraries from the
archive: a cached private runtime carries extensions this project does not
declare, and tpc does not add their system libraries for a static libphp.a
(-lonig -lxml2 -lsqlite3 -lz -lresolv -lcurl -lssl -lcrypto -liconv, the last
three behind keg-only brew prefixes). It also rejects a phpx older than the
php::empty_string API the compiler now emits, which otherwise fails in every
translation unit with a C++ error that does not point at the version gap.

McpBinaryTest picks the binary by platform, accepts TYPEPHP_MCP_BINARY, and now
drives the compiled artifact through both exec() paths: get_index_info's
tpc+git and check_code's tpc --dry.

Validation: 36 tests / 383 assertions pass with one platform-scoped skip
(vswhere); all 12 tools answer byte-identically from the AOT binary and from
interpreted PHP apart from check_code's uniqid() build directory; pointing
PHP_HOME at a runtime without an embed library turns all three check_code
assertions red together, which is the control that they own the compiler path.
Linux shares the script but is not yet measured.
---
 tools/typephp-mcp/.gitignore              |   1 +
 tools/typephp-mcp/README.md               |  61 +++++++++-
 tools/typephp-mcp/build.sh                | 137 ++++++++++++++++++++++
 tools/typephp-mcp/tests/McpBinaryTest.php |  59 +++++++++-
 4 files changed, 252 insertions(+), 6 deletions(-)
 create mode 100755 tools/typephp-mcp/build.sh

diff --git a/tools/typephp-mcp/.gitignore b/tools/typephp-mcp/.gitignore
index a5b7451f..8d84beb3 100644
--- a/tools/typephp-mcp/.gitignore
+++ b/tools/typephp-mcp/.gitignore
@@ -1 +1,2 @@
 /build.log
+/typephp_mcp
diff --git a/tools/typephp-mcp/README.md b/tools/typephp-mcp/README.md
index 95951243..7eb87cf1 100644
--- a/tools/typephp-mcp/README.md
+++ b/tools/typephp-mcp/README.md
@@ -32,6 +32,8 @@
 
 ## 构建
 
+### Windows
+
 前置：VS 2022 BuildTools（`vcvars64.bat`，经 vswhere 自动定位）与一个 tpc 包。
 
 ```bat
@@ -52,6 +54,29 @@ tools\typephp-mcp\build.bat
 产物 `typephp_mcp.exe` 及运行时 DLL（phpx/php8ts/gmp/mpfr/mpdec）都在本目录，
 **不需要改 PATH**。
 
+### macOS / Linux
+
+```bash
+tools/typephp-mcp/build.sh
+```
+
+Windows 有一个 tpc 发行包目录装着 phpx/PHP SDK，Unix 侧没有，所以 `build.sh` 改为定位
+**宿主 embed 运行时**（顺序：显式 `PHP_HOME`/`PHPX_HOME` → `~/.typephp/php-builder/php-*/install`
+里最新的私有运行时 → 仓库 `vendor/swoole/phpx`）：
+
+| 前置 | 要求 | 实测踩坑 |
+|---|---|---|
+| clang | `xcode-select --install` | tpc 启动即打印 `Initialized platform/backend: macOS + Clang` |
+| `PHP_HOME` | `lib/libphp.{a,dylib}` | Homebrew 的 php 只建 cli SAPI，**没有 libphp**；`--dry` 也会直接 Fatal |
+| `PHPX_HOME` | `include/phpx.h` + `lib/libphpx.{a,dylib}` | 编译器现在生成 `php::empty_string`，phpx 需 ≥ 该 API（`composer update swoole/phpx`），`build.sh` 会先校验再报错 |
+| 链接库 | — | 私有运行时的扩展集通常比本项目声明的多，`libphp.a` 于是引用 tpc 不认识的 `-lonig/-lxml2/-lsqlite3/-lz/-lresolv/-lcurl/-lssl -lcrypto/-liconv`；`build.sh` 用 `ar -t` 探测实际对象后补齐，iconv/openssl 是 brew keg-only 还要带 `-L` |
+
+产物是本目录的 `typephp_mcp`（无 `.exe` 后缀，Mach-O arm64，约 25 MB），依赖 gmp/mpfr/oniguruma
+等 brew dylib 的绝对路径，换机需重装同样的 brew 包。
+
+以上 macOS 路径为实测；`build.sh` 同时按 Linux 写（`uname` 分支只影响 libiconv 那条），
+**Linux 侧尚未实跑验证**。
+
 ## 运行 / 接入 MCP 客户端
 
 ```bat
@@ -59,12 +84,23 @@ set TYPEPHP_MCP_ROOT=D:\git\php\aot-compiler
 tools\typephp-mcp\typephp_mcp.exe
 ```
 
+macOS / Linux（`check_code` 要调编译器，所以 `PHP_HOME`/`PHPX_HOME` 与构建时同一套）：
+
+```bash
+export TYPEPHP_MCP_ROOT=/Volumes/data/git/php/typephp-compiler
+export PHP_HOME=$HOME/.typephp/php-builder/php-8.5.11-<hash>/install
+export PHPX_HOME=<phpx 树：include/phpx.h + lib/libphpx.a>
+tools/typephp-mcp/typephp_mcp
+```
+
 环境变量：
 
 | 变量 | 默认 | 说明 |
 |---|---|---|
-| `TYPEPHP_MCP_ROOT` | 从 cwd 向上找 `bin/tpc.php` + `docs/`，再退到构建期默认值 | 仓库根 |
+| `TYPEPHP_MCP_ROOT` | 从 cwd 向上找 `bin/tpc.php` + `docs/`，再退到构建期默认值 | 仓库根。兜底常量 `TYPEPHP_MCP_DEFAULT_ROOT` 是 Windows 开发机路径，**在 mac 上永远命中不到**，客户端从别处拉起 server 时必须显式设置 |
 | `TYPEPHP_MCP_PHP` | `php`（PATH 查找） | `check_code` / `get_index_info` 调编译器用的 PHP |
+| `PHP_HOME` / `PHPX_HOME` | 继承调用方环境 | 这两个只被 `check_code`/`get_index_info` 间接使用（tpc 自己读）；mac 上不设就是 `The host PHP embed library is missing`，工具会如实回报成 `FAILED (exit 255)` |
+| `TYPEPHP_MCP_PROJECT_ROOT` | 未设 | 客户端不发 MCP roots 时，手动把 TypePHP 项目路径并入默认检索集（分隔符 `;` 或 `:` 都认） |
 
 Finch（`~/.finch/mcp/servers.json`，对象数组）：
 
@@ -122,7 +158,22 @@ php vendor/bin/phpunit tools/typephp-mcp/tests/
 - `McpServerTest`：协议分发 + 12 个工具的逻辑单测（普通 PHP 直接跑；
   源码刻意保持在 stock PHP 与 TypePHP 的交集内，解释执行与 AOT 编译跑同一份代码）。
 - `McpBinaryTest`：驱动编译产物跑真实 stdio 会话，含逐条 flush 超时校验
-  （未构建时自动 skip）。
+  （未构建时自动 skip）。二进制按平台取 `typephp_mcp.exe` / `typephp_mcp`，
+  也可用 `TYPEPHP_MCP_BINARY=<path>` 指定。
+
+`check_code` 相关断言（两个测试文件里共 3 条）要求调用方环境里有一个能跑 `tpc --dry`
+的 embed 运行时；Windows 靠 tpc 包，macOS/Linux 靠 `PHP_HOME`/`PHPX_HOME`（见"构建"）。
+没设这些变量时它们会红，报的是编译器那句 `The host PHP embed library is missing`，
+不是本项目的问题。
+
+macOS 实测（2026-10-24，Apple Silicon，PHP 8.5.7 + 私有 8.5.11 embed 运行时 + phpx 2.9.4）：
+`php vendor/bin/phpunit tools/typephp-mcp/tests/` → 36 用例 / 383 断言全绿，
+唯一 skip 是 `testMsvcBinDirDiscovery`（vswhere 只在 Windows 存在）。
+AOT 产物 25 MB，真实 stdio 会话里 12 个工具与两条 `exec()` 通路
+（`get_index_info` 的 tpc+git、`check_code` 的 tpc --dry）均正常。
+逐个工具比对 AOT 产物与解释执行同一份代码：12 条回复逐字节相同，唯一差异是 `check_code`
+里那个 `uniqid()` 临时构建目录名。反向对照：把 `PHP_HOME` 指向没有 embed 库的目录，
+三条 `check_code` 断言（两个单测 + 产物会话各一）一起变红，说明这几条断言真的在管编译器通路。
 
 ## 已知问题（编译器侧，非本项目 bug）
 
@@ -131,3 +182,9 @@ php vendor/bin/phpunit tools/typephp-mcp/tests/
 `src/Parser/ConstantExpressionTrait.php::parseConstFetch()` 的常量折叠路径），
 运行时 `fwrite()/fgets()` 会抛 `TypeError`。规避：`main.php` 统一用
 `fopen('php://stdin'/'php://stdout'/'php://stderr')` 打开标准流。
+
+macOS 链接期缺扩展依赖：走私有 embed **静态** `libphp.a` 时，tpc 不按运行时的实际扩展集推导
+系统库，除 gmp/mpfr/c++ 外的 `-lonig -lxml2 -lsqlite3 -lz -lresolv -lcurl -lssl -lcrypto -liconv`
+都要应用侧补上，`build.sh` 用 `ar -t` 探测归档对象后补全（iconv/openssl 还是 brew keg-only，
+要带 `-L`）。CI 的 macos-arm64 作业没踩到，因为它用 setup-php 的**共享** `libphp.dylib`
+（依赖由 dyld 解析），只有静态 embed 运行时才需要这一串 `-l`。
diff --git a/tools/typephp-mcp/build.sh b/tools/typephp-mcp/build.sh
new file mode 100755
index 00000000..c4ca65a4
--- /dev/null
+++ b/tools/typephp-mcp/build.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Build typephp_mcp with TypePHP (AOT) on macOS/Linux.
+#
+# All paths are resolved relative to this script's location:
+#   <script dir>         project.yml, build/, output binary
+#   <script dir>/../..   repo root (bin/tpc.php)
+#
+# Unlike build.bat there is no toolchain installer to call: clang must be on
+# PATH (xcode-select --install) and the PHP/PHPX runtime has to be located,
+# because there is no per-platform tpc package directory to default to.
+#
+#   PHP_HOME   prefix providing lib/libphp.{a,dylib} (the embed SAPI)
+#   PHPX_HOME  phpx tree providing include/phpx.h and lib/libphpx.{a,dylib}
+#
+# Resolution order: explicit environment, then the newest private runtime that
+# tpc's php-builder left under ~/.typephp/php-builder. When neither is available,
+# build one (compiles php-src plus a static phpx; tpc only offers php-builder
+# interactively, so the flag has to be explicit in a scripted shell):
+#
+#   php bin/tpc.php tools/typephp-mcp/project.yml --php-builder='extensions: []'
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+cd "$SCRIPT_DIR"
+REPO_ROOT=$(cd -- "$SCRIPT_DIR/../.." && pwd)
+
+php_home=${PHP_HOME:-}
+phpx_home=${PHPX_HOME:-}
+
+if [[ -z "$php_home" ]]; then
+    for candidate in $(ls -1d "${HOME}"/.typephp/php-builder/php-*/install 2>/dev/null | sort -r); do
+        if [[ -f "$candidate/lib/libphp.a" || -f "$candidate/lib/libphp.dylib" ]]; then
+            php_home=$candidate
+            break
+        fi
+    done
+fi
+
+if [[ -z "$phpx_home" ]]; then
+    for candidate in "${REPO_ROOT}/vendor/swoole/phpx" "${php_home}/phpx" "$php_home"; do
+        if [[ -f "$candidate/include/phpx.h" ]] \
+            && { [[ -f "$candidate/lib/libphpx.a" ]] || [[ -f "$candidate/lib/libphpx.dylib" ]]; }; then
+            phpx_home=$candidate
+            break
+        fi
+    done
+fi
+
+if [[ -z "$php_home" || -z "$phpx_home" ]]; then
+    echo "[build] ERROR: no usable PHP/PHPX runtime found."
+    echo "[build]   PHP_HOME needs lib/libphp.a (or .dylib);"
+    echo "[build]   PHPX_HOME needs include/phpx.h plus lib/libphpx.a (or .dylib)."
+    echo "[build] Export them, or build a private runtime once with --php-builder"
+    echo "[build] (see the header of this script)."
+    exit 1
+fi
+
+# The compiler emits php::empty_string; a phpx checkout older than that API
+# compiles every translation unit and then dies in the link, so fail here with
+# the fix instead. composer.lock is not committed, so a stale vendor/ is easy
+# to carry over from an unrelated project.
+if ! grep -q "empty_string" "$phpx_home/include/phpx.h"; then
+    echo "[build] ERROR: ${phpx_home} is too old for this compiler (include/phpx.h lacks php::empty_string)."
+    echo "[build] Update it (composer update swoole/phpx) or point PHPX_HOME at a current phpx tree."
+    exit 1
+fi
+
+export PHP_HOME="$php_home" PHPX_HOME="$phpx_home"
+echo "[build] PHP_HOME=${PHP_HOME}"
+echo "[build] PHPX_HOME=${PHPX_HOME}"
+
+# keg-only brew formulae are not symlinked into the prefix root.
+brew_keg_lib() {
+    local dir
+    for dir in "/opt/homebrew/opt/$1/lib" "/usr/local/opt/$1/lib"; do
+        if [[ -d "$dir" ]]; then
+            echo "$dir"
+            return
+        fi
+    done
+    echo ""
+}
+
+# A private runtime cached from an unrelated project usually carries more
+# extensions than this project declares, and libphp.a then references system
+# libraries tpc does not know about (-lonig for mbstring, -lresolv for sockets,
+# ...). Derived from the archive contents so the list is not hand-maintained.
+LINK_FLAGS=()
+LIBPHP="${PHP_HOME}/lib/libphp.a"
+if [[ -f "$LIBPHP" ]]; then
+    OBJECTS=$(ar -t "$LIBPHP" 2>/dev/null || true)
+    while IFS='|' read -r probe libs keg; do
+        [[ -z "$probe" ]] && continue
+        if grep -qE "$probe" <<< "$OBJECTS"; then
+            for lib in $libs; do
+                LINK_FLAGS+=(-l "$lib")
+            done
+            if [[ -n "$keg" ]]; then
+                LINK_FLAGS+=(-L "$(brew_keg_lib "$keg")")
+            fi
+        fi
+    done <<'PROBES'
+^php_mbregex\.o$|onig|oniguruma
+^libxml\.o$|xml2|
+^sqlite3\.o$|sqlite3|
+^zlib\.o$|z|
+^sockets\.o$|resolv|
+^curl_.*\.o$|curl|
+^openssl\.o$|ssl crypto|openssl@3
+PROBES
+fi
+if [[ "$(uname)" == "Darwin" ]]; then
+    # PHP's mac runtime references libiconv, and the brew build of it is
+    # keg-only, so the library search path has to be given explicitly.
+    LINK_FLAGS+=(-l iconv)
+    if [[ -n "$(brew_keg_lib libiconv)" ]]; then
+        LINK_FLAGS+=(-L "$(brew_keg_lib libiconv)")
+    fi
+fi
+
+if [[ ${#LINK_FLAGS[@]} -gt 0 ]]; then
+    echo "[build] extra link flags: ${LINK_FLAGS[*]}"
+fi
+
+rm -rf build
+echo "[build] Compiling typephp-mcp"
+php "${REPO_ROOT}/bin/tpc.php" project.yml -O2 --job 1 --build-dir build \
+    --no-color --no-progress -o typephp_mcp ${LINK_FLAGS[@]+"${LINK_FLAGS[@]}"}
+
+BINARY="${SCRIPT_DIR}/typephp_mcp"
+if [[ ! -x "$BINARY" ]]; then
+    echo "[build] ERROR: typephp_mcp was not produced."
+    exit 1
+fi
+file "$BINARY"
+otool -L "$BINARY" | sed -n '2,20p'
+echo "[build] Done: $BINARY"
diff --git a/tools/typephp-mcp/tests/McpBinaryTest.php b/tools/typephp-mcp/tests/McpBinaryTest.php
index 422cc7a6..72a97ef7 100644
--- a/tools/typephp-mcp/tests/McpBinaryTest.php
+++ b/tools/typephp-mcp/tests/McpBinaryTest.php
@@ -2,6 +2,8 @@
 
 use PHPUnit\Framework\TestCase;
 
+require_once __DIR__ . '/../src/CompilerOracle.php';
+
 /**
  * Integration test: drives the compiled typephp_mcp.exe over a real stdio
  * session, including a live per-message flush check (the reply must arrive
@@ -9,18 +11,39 @@
  */
 final class McpBinaryTest extends TestCase
 {
-    private const EXECUTABLE = __DIR__ . '/../typephp_mcp.exe';
+    private const BUILD_DIR = __DIR__ . '/..';
 
     private const REPO_ROOT = __DIR__ . '/../../..';
 
+    /**
+     * The compiled binary is `typephp_mcp.exe` on Windows and `typephp_mcp`
+     * elsewhere; TYPEPHP_MCP_BINARY points the test at a specific artifact.
+     */
+    private static function executable(): string
+    {
+        $override = getenv('TYPEPHP_MCP_BINARY');
+        if (is_string($override) && $override !== '') {
+            return $override;
+        }
+        $suffix = PHP_OS_FAMILY === 'Windows' ? '.exe' : '';
+        return self::BUILD_DIR . '/typephp_mcp' . $suffix;
+    }
+
+    private static function buildHint(): string
+    {
+        $script = PHP_OS_FAMILY === 'Windows' ? 'build.bat' : './build.sh';
+        return 'typephp_mcp not built; run tools/typephp-mcp/' . $script;
+    }
+
     public function testStdioMcpSession(): void
     {
-        if (!is_file(self::EXECUTABLE)) {
-            self::markTestSkipped('typephp_mcp.exe not built; run tools/typephp-mcp/build.bat');
+        $executable = self::executable();
+        if (!is_file($executable)) {
+            self::markTestSkipped(self::buildHint());
         }
 
         $process = proc_open(
-            [self::EXECUTABLE],
+            [$executable],
             [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']],
             $pipes,
             self::REPO_ROOT
@@ -70,6 +93,34 @@ public function testStdioMcpSession(): void
             self::assertNotNull($reply);
             self::assertSame(JSON_ERROR_NONE, json_last_error());
             self::assertStringContainsString('docs/zh-cn/', $reply['result']['content'][0]['text']);
+
+            // The two tools that shell out. Reading them from the compiled
+            // process is what proves exec() works in the AOT binary; the
+            // interpreted suite cannot cover that on any platform.
+            $call = [
+                'jsonrpc' => '2.0',
+                'id' => 5,
+                'method' => 'tools/call',
+                'params' => ['name' => 'get_index_info', 'arguments' => []],
+            ];
+            self::assertNotFalse(fwrite($pipes[0], (string) json_encode($call) . "\n"));
+            $reply = $this->readReply($pipes[1], 30.0);
+            self::assertNotNull($reply);
+            self::assertStringContainsString('git_commit: ', $reply['result']['content'][0]['text']);
+            self::assertStringContainsString('tpc_version: ', $reply['result']['content'][0]['text']);
+
+            if (CompilerOracle::phpBinary() !== '') {
+                $call = [
+                    'jsonrpc' => '2.0',
+                    'id' => 6,
+                    'method' => 'tools/call',
+                    'params' => ['name' => 'check_code', 'arguments' => ['path' => 'examples/hello.php']],
+                ];
+                self::assertNotFalse(fwrite($pipes[0], (string) json_encode($call) . "\n"));
+                $reply = $this->readReply($pipes[1], 60.0);
+                self::assertNotNull($reply, 'no check_code reply within timeout');
+                self::assertStringStartsWith('OK:', $reply['result']['content'][0]['text']);
+            }
         } finally {
             fclose($pipes[0]);
             fclose($pipes[1]);