diff --git a/.github/actions/unix-arm64-build/action.yml b/.github/actions/unix-arm64-build/action.yml
index e993449a..bdba46f1 100644
--- a/.github/actions/unix-arm64-build/action.yml
+++ b/.github/actions/unix-arm64-build/action.yml
@@ -195,6 +195,36 @@ runs:
         output="$("${smoke_binary}")"
         test "${output}" = '${{ inputs.smoke-output }}'
 
+    - name: Build typephp-mcp
+      shell: bash
+      run: |
+        export PHP_HOME="$(php-config --prefix)"
+        bash tools/typephp-mcp/build.sh
+        test -x tools/typephp-mcp/typephp_mcp
+
+    - name: Run typephp-mcp native smoke
+      shell: bash
+      run: |
+        # Point check_code at the compiler this job just built, so it never
+        # depends on the auto-detection order.
+        export TYPEPHP_MCP_TPC="${PWD}/tpc"
+        # 10 minute wall-clock limit: a wedged process must fail the stage
+        # rather than hold the job open. GNU timeout is missing on macOS, and
+        # a plain fallback there let a non-replying server hang the job
+        # forever, so use perl (shipped with macOS) as the watchdog.
+        run_smoke() {
+          if command -v timeout >/dev/null 2>&1; then
+            timeout 600 "$@"
+          elif command -v perl >/dev/null 2>&1; then
+            perl -e 'alarm shift; exec @ARGV' 600 "$@"
+          else
+            echo "[smoke] ERROR: neither timeout nor perl is available for the watchdog" >&2
+            return 1
+          fi
+        }
+        run_smoke php tools/typephp-mcp/tests/mcp-binary-smoke.php tools/typephp-mcp/typephp_mcp "${{ github.workspace }}"
+        run_smoke php tools/typephp-mcp/tests/mcp-binary-smoke.php --interpreted "${{ github.workspace }}"
+
     - name: Show native dependencies
       shell: bash
       run: |
diff --git a/.github/workflows/linux-x64.yml b/.github/workflows/linux-x64.yml
index 278ff326..9fddf0e7 100644
--- a/.github/workflows/linux-x64.yml
+++ b/.github/workflows/linux-x64.yml
@@ -195,6 +195,7 @@ jobs:
         php: ["8.4", "8.5"]
     env:
       PHPX_HOME: ${{ github.workspace }}/third_party/phpx
+      TYPEPHP_MCP_REQUIRE_BINARY: '1'
 
     steps:
       - name: Checkout TypePHP
@@ -274,6 +275,19 @@ jobs:
         shell: bash
         run: echo "LD_LIBRARY_PATH=${PHPX_HOME}/lib:$(php-config --prefix)/lib" >> "${GITHUB_ENV}"
 
+      - name: Build typephp-mcp
+        shell: bash
+        run: |
+          php_home="$(php-config --prefix)"
+          export PHP_HOME="${php_home}"
+          # Lock critical section first: fails fast and needs no toolchain.
+          bash tools/typephp-mcp/tests/build-lock-test.sh
+          bash tools/typephp-mcp/build.sh
+          test -x tools/typephp-mcp/typephp_mcp
+          # Pin check_code to the compiler built above rather than relying on
+          # the auto-detection order (the repository also ships bin/tpc.php).
+          echo "TYPEPHP_MCP_TPC=${PWD}/tpc" >> "${GITHUB_ENV}"
+
       - name: Run PHPUnit
         run: vendor/bin/phpunit
 
diff --git a/.github/workflows/windows-build.yml b/.github/workflows/windows-build.yml
index 0d991fc3..4a126ce7 100644
--- a/.github/workflows/windows-build.yml
+++ b/.github/workflows/windows-build.yml
@@ -348,6 +348,65 @@ jobs:
               throw 'The compiler did not produce tpc.exe'
           }
 
+      - name: Build typephp-mcp
+        shell: pwsh
+        # Build from the tool directory like build.bat does: tpc writes the
+        # executable next to project.yml, not next to the caller's cwd.
+        working-directory: tools/typephp-mcp
+        run: |
+          $ErrorActionPreference = 'Stop'
+          # The compiled compiler declares ZEND_MOD_REQUIRED for mbstring and
+          # links phpx.dll from the PHPX build directory, so it needs both the
+          # packaged php.ini and that directory on PATH - the same setup every
+          # other step that runs tpc.exe uses.
+          $env:PHPRC = Join-Path $env:PHP_HOME 'php.ini'
+          $env:PATH = "$env:PHPX_HOME\build;$env:PATH"
+          & ..\..\tpc.exe project.yml --job $env:BUILD_JOBS --no-progress
+          if ($LASTEXITCODE -ne 0) {
+              throw "typephp-mcp build failed with exit code $LASTEXITCODE"
+          }
+          $binary = Join-Path '${{ github.workspace }}' 'tools\typephp-mcp\typephp_mcp.exe'
+          if (-not (Test-Path $binary)) {
+              throw "typephp_mcp.exe was not generated: $binary"
+          }
+
+      - name: Run typephp-mcp native smoke
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $env:PHPRC = Join-Path $env:PHP_HOME 'php.ini'
+          # The AOT binary links PHPX and the PHP runtime; the dev-machine
+          # build script copies their DLLs next to the exe, CI uses PATH.
+          $env:PATH = "$env:PHPX_HOME\build;$env:PATH"
+          # Point check_code at the compiler this job just built. Relying on
+          # auto-detection would fall back to `php bin/tpc.php`, which needs
+          # the phpy extension this runner does not install.
+          $env:TYPEPHP_MCP_TPC = Join-Path '${{ github.workspace }}' 'tpc.exe'
+          $binary = Join-Path '${{ github.workspace }}' 'tools\typephp-mcp\typephp_mcp.exe'
+          # Hard wall-clock limit. Do NOT redirect the child's output: the MCP
+          # server spawns compiler children that inherit the handles, so a
+          # redirected stream never reaches EOF and reading it hangs the step
+          # forever (that is what kept this job open for 30+ minutes). Let the
+          # output go straight to the job log and only bound the wait.
+          $psi = [Diagnostics.ProcessStartInfo]::new()
+          $psi.FileName = (Get-Command php).Source
+          $psi.ArgumentList.Add('tools\typephp-mcp\tests\mcp-binary-smoke.php')
+          $psi.ArgumentList.Add($binary)
+          $psi.ArgumentList.Add('${{ github.workspace }}')
+          $psi.UseShellExecute = $false
+          $psi.WorkingDirectory = '${{ github.workspace }}'
+          $process = [Diagnostics.Process]::new()
+          $process.StartInfo = $psi
+          if (-not $process.Start()) { throw 'Unable to start the typephp-mcp smoke driver' }
+          if (-not $process.WaitForExit(600000)) {
+              $process.Kill($true)
+              $process.WaitForExit()
+              throw 'typephp-mcp native smoke exceeded its 10 minute limit'
+          }
+          if ($process.ExitCode -ne 0) {
+              throw "typephp-mcp native smoke failed with exit code $($process.ExitCode)"
+          }
+
       - name: Test bootstrap signatures
         shell: pwsh
         run: |
diff --git a/.gitignore b/.gitignore
index 9d7090d9..d1418d90 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,3 +37,4 @@ tests/**/*.sh
 /tests/wasm/harness/node_modules/
 /ide-helper/
 /debug/
+/tools/typephp-mcp/build/
diff --git a/docs/en/CLASS_INHERITANCE.md b/docs/en/CLASS_INHERITANCE.md
index 0b47bfff..19faf546 100644
--- a/docs/en/CLASS_INHERITANCE.md
+++ b/docs/en/CLASS_INHERITANCE.md
@@ -35,21 +35,18 @@ interface BaseInterface {}
 class MyClass implements BaseInterface {}
 ```
 
-### Rule 3: Cannot Inherit Internal Classes
+### Rule 3: Native Classes and Plain Zend Classes Cannot Inherit from Each Other
 
 ```php
-// ❌ Wrong: inheriting a PHP internal class
+// ✅ Correct: inheriting a Zend internal class (detected via
+// Reflection::isInternalClass at compile time)
 class MyArray extends ArrayObject {}
-// Compile error: Class `MyArray` Cannot inherit built-in class `ArrayObject`
+class MyDb extends PDO {}
 
-// ✅ Correct: use the composition pattern
-class MyContainer {
-    private ArrayObject $storage;
-    
-    public function __construct() {
-        $this->storage = new ArrayObject();
-    }
-}
+// ❌ Wrong: a Native class inheriting from a Zend class (or vice versa)
+// class MyNative extends SomeZendClass {}   // Native cannot extend Zend
+// class MyZend extends SomeNativeClass {}   // Zend cannot extend Native
+// Compile error: Native and ZendVM-backed classes cannot inherit from each other
 ```
 
 ---
@@ -73,27 +70,31 @@ class MyContainer {
 
 ### Checking Code Location
 
-The relevant implementation is in `src/Php/Translator.php`:
+The relevant implementation is in `src/Translator.php` (inheritance checks) and
+`src/Preprocessor.php` (internal-class detection):
 
 ```php
-if ($extends) {
-    $parentClass = $this->getParentClass($class->extends);
-    if ($this->hasNativeClass($parentClass)) {
-        // The parent class is a defined native class
-        $parent = $this->getClassDef($parentClass);
+// src/Translator.php — compile-time inheritance checks (v0.9.5)
+if ($this->classDef->extends and !$this->classDef->inheritedFromInternalClass) {
+    $parentClass = $this->getNamespacedClassName($this->parseIdentifier($class->extends));
+    if ($this->hasClass($parentClass)) {
+        $parent = $this->getClass($parentClass);
+        if ($this->classDef->nativeObject !== $parent->nativeObject) {
+            $this->fatalError($class,
+                'Native and ZendVM-backed classes cannot inherit from each other');
+        }
         if ($parent->flags & Modifiers::FINAL) {
             $this->fatalError($class, "Class `{$this->class}` cannot extend final class `{$parentClass}`");
         }
-        $this->classDef->extends = $parentClass;
+        $this->assertReadonlyInheritanceContract($class, $parentClass, ...);
     } else {
-        // Check whether it is a PHP internal class
-        if (Reflection::isInternalClass($parentClass)) {
-            $this->fatalError($class, "Class `{$this->class}` Cannot inherit built-in class `$parentClass`");
-        } else {
-            $this->fatalError($class, "Class `{$this->class}` inherits from a non-existent class `$parentClass`");
-        }
+        $this->fatalError($class, "Class `{$this->class}` inherits from a non-existent class `{$parentClass}`");
     }
 }
+// src/Preprocessor.php — internal-class detection: when the parent is a
+// built-in class, inheritedFromInternalClass is set and only the readonly
+// contract is checked against the host runtime's reflection. Inheriting
+// built-in classes is allowed.
 ```
 
 ---
@@ -312,31 +313,32 @@ class MyService {
 }
 ```
 
-### Example 3: Inheriting a PHP Internal Class
+### Example 3: A Native Class Inheriting from a Zend Class
 
 ```php
 <?php
-// ❌ Wrong: cannot inherit PDO
-class MyDatabase extends PDO {
-    // ...
-}
+// ❌ Wrong: a Zend class inheriting from a Native class (or the reverse)
+class MyNative extends SomeZendClass {}
 
 function main() {
-    $db = new MyDatabase('mysql:host=localhost;dbname=test');
+    $obj = new MyNative();
 }
 ?>
 ```
 
 **Compile error**:
 ```
-Fatal error: Class `MyDatabase` Cannot inherit built-in class `PDO`
+Fatal error: Native and ZendVM-backed classes cannot inherit from each other
 in /path/to/file.php on line X
 ```
 
-**Solution**:
+**Note**: inheriting Zend internal classes (such as `PDO` or `ArrayObject`) is
+**allowed**; composition remains a recommended style but is not enforced by the
+compiler.
+
 ```php
 <?php
-// ✅ Use the composition pattern
+// ✅ Composition pattern (recommended style, not enforced)
 class MyDatabase {
     private PDO $connection;
     
@@ -532,7 +534,7 @@ class EnhancedStorage {
 | **Check timing** | Compile time | Runtime |
 | **Error discovery** | Reports an error immediately at compile time | Reports an error only when the code is executed |
 | **autoload support** | ❌ Not supported as a parent class | ✅ Fully supported |
-| **Inheriting internal classes** | ❌ Forbidden | ✅ Allowed (partially) |
+| **Inheriting internal classes** | ✅ Allowed (Zend internal classes; readonly contract checked via reflection) | ✅ Allowed (partially) |
 | **Performance impact** | No runtime overhead | Has runtime checking overhead |
 
 ---
@@ -566,5 +568,5 @@ A: The use of traits is likewise restricted. Traits must be visible at compile t
 
 ---
 
-**Last updated**: March 20, 2024
-**Applicable version**: PHP AOT Compiler v1.x
+**Last updated**: October 2026 (aligned with v0.9.5 behavior: Zend internal classes can be inherited)
+**Applicable version**: PHP AOT Compiler v0.9.5
diff --git a/docs/zh-cn/CLASS_INHERITANCE.md b/docs/zh-cn/CLASS_INHERITANCE.md
index 8fadcb7c..b6192988 100644
--- a/docs/zh-cn/CLASS_INHERITANCE.md
+++ b/docs/zh-cn/CLASS_INHERITANCE.md
@@ -35,21 +35,17 @@ interface BaseInterface {}
 class MyClass implements BaseInterface {}
 ```
 
-### 规则三：不能继承内部类（Internal Class）
+### 规则三：Native 类与普通 Zend 类不能互相继承
 
 ```php
-// ❌ 错误：继承 PHP 内部类
+// ✅ 正确：继承 Zend 内部类（编译期按 Reflection::isInternalClass 判定）
 class MyArray extends ArrayObject {}
-// 编译错误：Class `MyArray` Cannot inherit built-in class `ArrayObject`
+class MyDb extends PDO {}
 
-// ✅ 正确：使用组合模式
-class MyContainer {
-    private ArrayObject $storage;
-    
-    public function __construct() {
-        $this->storage = new ArrayObject();
-    }
-}
+// ❌ 错误：Native 类与普通 Zend 类互继
+// class MyNative extends SomeZendClass {}   // Native 类不能继承 Zend 类
+// class MyZend extends SomeNativeClass {}   // Zend 类不能继承 Native 类
+// 编译错误：Native and ZendVM-backed classes cannot inherit from each other
 ```
 
 ---
@@ -73,27 +69,28 @@ class MyContainer {
 
 ### 检查代码位置
 
-相关实现在 `src/Php/Translator.php`：
+相关实现在 `src/Translator.php`（类继承检查）与 `src/Preprocessor.php`（内部类判定）：
 
 ```php
-if ($extends) {
-    $parentClass = $this->getParentClass($class->extends);
-    if ($this->hasNativeClass($parentClass)) {
-        // 父类是已定义的 native 类
-        $parent = $this->getClassDef($parentClass);
+// src/Translator.php — 编译期继承检查（v0.9.5）
+if ($this->classDef->extends and !$this->classDef->inheritedFromInternalClass) {
+    $parentClass = $this->getNamespacedClassName($this->parseIdentifier($class->extends));
+    if ($this->hasClass($parentClass)) {
+        $parent = $this->getClass($parentClass);
+        if ($this->classDef->nativeObject !== $parent->nativeObject) {
+            $this->fatalError($class,
+                'Native and ZendVM-backed classes cannot inherit from each other');
+        }
         if ($parent->flags & Modifiers::FINAL) {
             $this->fatalError($class, "Class `{$this->class}` cannot extend final class `{$parentClass}`");
         }
-        $this->classDef->extends = $parentClass;
+        $this->assertReadonlyInheritanceContract($class, $parentClass, ...);
     } else {
-        // 检查是否为 PHP 内部类
-        if (Reflection::isInternalClass($parentClass)) {
-            $this->fatalError($class, "Class `{$this->class}` Cannot inherit built-in class `$parentClass`");
-        } else {
-            $this->fatalError($class, "Class `{$this->class}` inherits from a non-existent class `$parentClass`");
-        }
+        $this->fatalError($class, "Class `{$this->class}` inherits from a non-existent class `{$parentClass}`");
     }
 }
+// src/Preprocessor.php — 内部类判定：父类是内置类时标记 inheritedFromInternalClass，
+// 后续只按宿主运行时反射校验 readonly 契约，允许继承。
 ```
 
 ---
@@ -312,31 +309,31 @@ class MyService {
 }
 ```
 
-### 示例三：继承 PHP 内部类
+### 示例三：Native 类与 Zend 类互继
 
 ```php
 <?php
-// ❌ 错误：不能继承 PDO
-class MyDatabase extends PDO {
-    // ...
-}
+// ❌ 错误：Zend 类继承 Native 类（或反向）
+class MyNative extends SomeZendClass {}
 
 function main() {
-    $db = new MyDatabase('mysql:host=localhost;dbname=test');
+    $obj = new MyNative();
 }
 ?>
 ```
 
 **编译错误**:
 ```
-Fatal error: Class `MyDatabase` Cannot inherit built-in class `PDO`
+Fatal error: Native and ZendVM-backed classes cannot inherit from each other
 in /path/to/file.php on line X
 ```
 
-**解决方案**:
+**说明**：继承 Zend 内部类（如 `PDO`、`ArrayObject`）是**允许**的；组合模式仍然是
+值得推荐的风格，但不是编译器强制要求。
+
 ```php
 <?php
-// ✅ 使用组合模式
+// ✅ 组合模式（推荐风格，非强制）
 class MyDatabase {
     private PDO $connection;
     
@@ -369,10 +366,10 @@ class UserService implements ServiceInterface {}
 class ProductService implements ServiceInterface {}
 ```
 
-### 2. 使用组合代替继承
+### 2. 优先组合而非继承
 
 ```php
-// ❌ 不推荐：继承内部类
+// ❌ 不推荐：为复用而继承（继承链过深或继承内部类以外的场景）
 class MyCollection extends ArrayCollection {
     // ...
 }
@@ -532,7 +529,7 @@ class EnhancedStorage {
 | **检查时机** | 编译期 | 运行时 |
 | **错误发现** | 编译时立即报错 | 执行到代码时才报错 |
 | **autoload 支持** | ❌ 不支持作为父类 | ✅ 完全支持 |
-| **继承内部类** | ❌ 禁止 | ✅ 允许（部分） |
+| **继承内部类** | ✅ 允许（Zend 内部类，readonly 契约按反射校验） | ✅ 允许（部分） |
 | **性能影响** | 无运行时开销 | 有运行时检查开销 |
 
 ---
@@ -566,5 +563,5 @@ A: Trait 的使用同样受到限制。Trait 必须在编译期可见，不能
 
 ---
 
-**最后更新**: 2024 年 3 月 20 日  
-**适用版本**: PHP AOT Compiler v1.x
+**最后更新**: 2026 年 10 月（对齐 v0.9.5 实际行为：允许继承 Zend 内部类）  
+**适用版本**: PHP AOT Compiler v0.9.5
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..8d84beb3
--- /dev/null
+++ b/tools/typephp-mcp/.gitignore
@@ -0,0 +1,2 @@
+/build.log
+/typephp_mcp
diff --git a/tools/typephp-mcp/README.md b/tools/typephp-mcp/README.md
new file mode 100644
index 00000000..5b300ceb
--- /dev/null
+++ b/tools/typephp-mcp/README.md
@@ -0,0 +1,206 @@
+# 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 子集合法性，返回结构化结果 `OK/FAILED stage=generate file=… diagnostics=N` + 逐条 `file:line[:col] 严重级别 消息`。只覆盖 C++ 生成阶段；编译/链接阶段不跑、不覆盖。工具自身执行失败（文件不存在 / PHP 或 SDK 缺失 / 编译器超时）以 `isError: true` 返回，与"用户代码不合格"的正常结果区分开 |
+| `list_restrictions` | 写码前必读。TypePHP 裁剪规则（程序结构/类型/引用/对象/控制流/std 表面/stub 契约/构建配置），可按 topic 查询 |
+| `get_symbol` | 按精确名字查函数/类/接口/trait/enum/const 声明，返回签名 + `file:line`（扫 src/、examples/、tests/std/）。支持完整命名空间（`TypePhp\Translator`）与 `Class::method`；大文件分块扫描（超过扫描上限会显式报告 Coverage 截断，绝不静默跳过） |
+| `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 边界安全。
+- **协议版本来真的**。`initialize` 按 MCP 版本规范应答：客户端请求的版本属于已实现集合才回显，
+  否则回本 server 支持的最新版（不假装支持任意版本）。`roots` 只在存在该能力的版本里声明，
+  工作区发现另有 `TYPEPHP_MCP_PROJECT_ROOT` 与 cwd 自动探测兜底。无 id 的通知（含 `tools/list`）一律不回复。
+- **编译器调用有生命周期控制**。`check_code` 通过受控子进程跑 tpc：超时、输出预算、进程树内存上限，
+  超时杀树并清理临时目录；服务在等待期间不会永久卡死。
+
+## 构建
+
+### Windows
+
+前置：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**。
+
+### 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 那条）。
+
+`build.sh` 在用户自管机器上遵守资源安全约束（AGENTS.md）：Linux 下先把清理和编译放进全用户构
+建锁 `${XDG_RUNTIME_DIR:-/tmp}/codex-build-$(id -u).lock` 的临界区（抢不到锁就不触碰 `build/`、不调用编译器），`-j1` 串行，并把整个构建进程树放进 systemd user scope
+（`MemoryMax` 为 8 GiB 或启动时可用内存的一半取小者，`MemorySwapMax=0` 禁 swap）——这才是整树
+内存总预算，`ulimit -v` 只是每进程第二道防线；scope 建不起来时拒绝构建并给出可用的受控入口
+（root scope / 容器）；CI 跑在专用 runner 上，改用可用逻辑 CPU 数。
+
+CI（本 PR 新增）在 **Linux x64 / Linux arm64 / macOS arm64 / Windows x64** 上都会实际构建 MCP
+产物并跑原生 stdio 冒烟测试；缺产物即判失败（不再靠"缺产物就 skip"证明兼容）。
+
+## 运行 / 接入 MCP 客户端
+
+```bat
+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/`，再退到源码相对默认值（`tools/typephp-mcp/src` 上三级） | **工具资源目录**（编译器 checkout），不是用户项目目录。默认值随源码位置解析，不再是写死的开发机路径；但 **AOT 产物内嵌的是构建机路径**，发布二进制从别处拉起时必须显式设置（否则以可操作的错误信息失败） |
+| `TYPEPHP_MCP_TPC` | 仓库根的 `tpc` / `tpc.exe` | `check_code` 调用的**编译好的 tpc 二进制**：不需要 PHP 解释器、也不需要 phpy 扩展（Windows 上尤其重要，因为解释执行 `php bin/tpc.php` 必须加载 phpy）。会先做一次有界的 `--version` 探测，跑不起来（缺运行时 DLL 或缺 mbstring）就退回解释执行 |
+| `TYPEPHP_MCP_PHP` | `php`（PATH 查找） | 只有走解释执行（`php bin/tpc.php`）时才需要；`get_index_info` 探测 tpc 版本同理 |
+| `PHP_HOME` / `PHPX_HOME` | 继承调用方环境 | 这两个只被 `check_code`/`get_index_info` 间接使用（tpc 自己读）；mac 上不设就是 `The host PHP embed library is missing`，工具会如实回报成 `isError: true` |
+| `TYPEPHP_MCP_PROJECT_ROOT` | 未设 | 客户端不发 MCP roots 时，手动把 TypePHP 项目路径并入默认检索集。分隔符：`;` 通用，POSIX 下 `:` 也认；**Windows 只认 `;`**（盘符里的冒号不能当分隔符） |
+| `TYPEPHP_MCP_COMPILE_TIMEOUT` | `120` | `check_code` 调编译器的超时秒数；超时杀掉整个子进程树并清理临时目录，服务保持可响应 |
+| `TYPEPHP_MCP_COMPILE_OUTPUT_LIMIT` | `65536` | 编译器输出捕获字节上限（仍持续排空管道，子进程不会被写满阻塞） |
+| `TYPEPHP_MCP_COMPILE_MEMORY_LIMIT_MB` | `4096` | POSIX 下编译器进程树的虚拟内存上限（MiB） |
+
+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`：用共享的 `McpBinaryDriver` 驱动编译产物跑真实 stdio 会话（逐条 flush 超时校验、
+  大文件符号、工具失败 `isError`、通知不回复、仓库外 cwd 启动、解释执行与 AOT 一致性）。二进制按平台取
+  `typephp_mcp.exe` / `typephp_mcp`，也可用 `TYPEPHP_MCP_BINARY=<path>` 指定；未构建时默认 skip，
+  设 `TYPEPHP_MCP_REQUIRE_BINARY=1`（CI 会设）则改为失败。
+- `tools/typephp-mcp/tests/mcp-binary-smoke.php`：独立 CI 驱动，落地同样的 wire 检查；`--interpreted`
+  跑解释执行入口 `run-interpreted.php`，用于和 AOT 产物对比。缺产物直接以退出码 1 失败。
+
+`check_code` 相关断言要求调用方环境里有一个能跑 `tpc --dry` 的 embed 运行时；Windows 靠 tpc 包，
+macOS/Linux 靠 `PHP_HOME`/`PHPX_HOME`（见"构建"）。没设这些变量时它们会红，报的是编译器那句
+`The host PHP embed library is missing`，不是本项目的问题。
+
+本 PR 起 CI 在 Linux x64/arm64、macOS arm64、Windows x64 上实际构建产物并跑原生冒烟，
+不再依赖"缺产物就 skip"来证明兼容。本机（Windows，PHP 8.5.11 + tpc_v0.9.5 包）实测：
+`php vendor/bin/phpunit --testsuite TypePhpMcpTests` → 45 用例 / 456 断言全绿；AOT 产物真实 stdio
+会话里 12 个工具与两条编译器通路（`get_index_info` 的 tpc+git、`check_code` 的 tpc --dry）均正常；
+反向对照：把 `PHP_HOME` 指向没有 embed 库的目录，`check_code` 断言一起变红，说明它们真的在管编译器通路。
+
+## 已知问题（编译器侧，非本项目 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')` 打开标准流。
+
+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.bat b/tools/typephp-mcp/build.bat
new file mode 100644
index 00000000..b0285be3
--- /dev/null
+++ b/tools/typephp-mcp/build.bat
@@ -0,0 +1,60 @@
+@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%"
+REM --job 1: user-managed machines build serially (AGENTS.md resource safety).
+REM CI builds the MCP binary with its own step, which passes --job %BUILD_JOBS%
+REM because a dedicated runner may use its available CPU count.
+"%PHP_HOME%\php.exe" "%REPO_ROOT%\bin\tpc.php" project.yml -O2 --job 1 --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/build.sh b/tools/typephp-mcp/build.sh
new file mode 100755
index 00000000..d214d668
--- /dev/null
+++ b/tools/typephp-mcp/build.sh
@@ -0,0 +1,264 @@
+#!/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: []'
+#
+# The compiler is the built ./tpc when the repository already has one (CI
+# builds it first), otherwise the interpreted `php bin/tpc.php`, which needs
+# the phpy extension that only the Linux x64 workflow enables.
+#
+# Resource safety (AGENTS.md): user-managed machines build serially under the
+# shared user-wide build lock (Linux) with a virtual memory cap for the whole
+# build tree. Dedicated CI runners instead build with their available CPU
+# count, so nothing here serializes a CI build.
+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" || -f "$candidate/lib/libphp.so" ]]; 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" ]] || [[ -f "$candidate/lib/libphpx.so" ]]; }; 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, .so or .dylib (the embed SAPI);"
+    echo "[build]   PHPX_HOME needs include/phpx.h plus lib/libphpx.a, .so 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
+
+# CI runners are dedicated: build with the available logical CPU count.
+# User-managed machines stay serial (AGENTS.md).
+if [[ "${CI:-}" == "true" || "${GITHUB_ACTION:-}" == "true" ]]; then
+    JOBS="${BUILD_JOBS:-$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1)}"
+else
+    JOBS=1
+fi
+
+TPC=(php "${REPO_ROOT}/bin/tpc.php")
+if [[ -x "${REPO_ROOT}/tpc" ]]; then
+    TPC=("${REPO_ROOT}/tpc")
+fi
+
+BUILD_CMD=("${TPC[@]}" project.yml -O2 --job "$JOBS" --build-dir build \
+    --no-color --no-progress -o typephp_mcp ${LINK_FLAGS[@]+"${LINK_FLAGS[@]}"})
+
+# Dedicated CI runs under its own budget and needs no lock or memory scope.
+# It must also not build here: the single build happens after the clean below,
+# so both paths compile exactly once.
+if [[ "${CI:-}" != "true" && "${GITHUB_ACTION:-}" != "true" ]]; then
+    # --- self-managed machine: resource safety (AGENTS.md) ---
+    # Budget for the build tree: 8 GiB or half of the memory available at
+    # startup, whichever is smaller.
+    limit_mb=8192
+    if [[ "$(uname)" == "Linux" && -r /proc/meminfo ]]; then
+        avail_kb=$(awk '/MemAvailable/{print $2}' /proc/meminfo 2>/dev/null || true)
+        if [[ -n "$avail_kb" && "$avail_kb" -gt 0 ]]; then
+            half_mb=$((avail_kb / 2048))
+            [[ "$half_mb" -lt "$limit_mb" ]] && limit_mb="$half_mb"
+        fi
+    elif [[ "$(uname)" == "Darwin" ]]; then
+        mem_mb=$(sysctl -n hw.memsize 2>/dev/null | awk '{print int($1/1048576)}' || true)
+        if [[ -n "$mem_mb" && "$mem_mb" -gt 0 ]]; then
+            half_mb=$((mem_mb / 2))
+            [[ "$half_mb" -lt "$limit_mb" ]] && limit_mb="$half_mb"
+        fi
+    fi
+
+    if [[ "$(uname)" == "Linux" ]]; then
+        # Whole-tree budget. ulimit -v caps the address space of EACH
+        # process; the compiler, its driver and every descendant each get
+        # their own cap, so N processes could reach N * limit together. A
+        # real total for the build tree needs a cgroup: this script enforces
+        # it by running the build inside a transient systemd user scope
+        # (cgroup v2) with a hard MemoryMax and swap forbidden. The probe
+        # verifies the scope mechanism works before anything is cleaned or
+        # compiled; when it cannot be established the build refuses to run
+        # and prints the controlled entries it accepts instead.
+        if ! command -v systemd-run >/dev/null 2>&1 \
+            || ! systemd-run --user --quiet --collect --scope true 2>/dev/null; then
+            {
+                echo "[build] ERROR: no whole-build-tree memory limit could be established (no working systemd user scope)."
+                echo "[build] A per-process cap is not a substitute: the build tree's TOTAL would be unbounded,"
+                echo "[build] so this script refuses to run an unprotected Linux build. Re-run it inside one of:"
+                echo "[build]   systemd-run --scope -p MemoryMax=${limit_mb}M -p MemorySwapMax=0 bash tools/typephp-mcp/build.sh"
+                echo "[build]   podman run --rm --memory=${limit_mb}m --memory-swap=${limit_mb}m -v \"\$PWD\":/src -w /src <image> \\"
+                echo "[build]     bash tools/typephp-mcp/build.sh"
+                echo "[build] (dedicated CI is exempt: it builds with the runner's CPU count under its own budget)"
+            } >&2
+            exit 1
+        fi
+    fi
+
+    # Second line of defence: a per-process virtual-memory cap, inherited by
+    # every descendant, so one runaway compiler cannot take the machine down.
+    # This is NOT the whole-tree budget - that is the systemd scope's
+    # MemoryMax above (Linux). macOS does not implement ulimit -v, so a
+    # rejection there is reported and the build continues: refusing outright
+    # would make the script unusable on that platform while protecting
+    # nothing. Anywhere else a rejection is fatal.
+    if ! ulimit -v "$((limit_mb * 1024))" 2>/dev/null; then
+        if [[ "$(uname)" == "Darwin" ]]; then
+            echo "[build] note: macOS has no ulimit -v; continuing without a per-process memory cap"
+        else
+            echo "[build] ERROR: cannot apply the per-process memory cap (${limit_mb} MiB)" >&2
+            exit 1
+        fi
+    else
+        echo "[build] per-process memory cap: ${limit_mb} MiB virtual, jobs: ${JOBS}"
+    fi
+
+    if [[ "$(uname)" == "Linux" ]]; then
+        if ! command -v flock >/dev/null 2>&1; then
+            echo "[build] ERROR: flock is required for the shared build lock but was not found" >&2
+            exit 1
+        fi
+        lock_file="${XDG_RUNTIME_DIR:-/tmp}/codex-build-$(id -u).lock"
+        echo "[build] acquiring build lock: ${lock_file}"
+        # Hold the lock on this shell's own descriptor instead of wrapping
+        # the build command: `flock -n <file> <cmd>` would only cover
+        # BUILD_CMD, and the clean below would run OUTSIDE the critical
+        # section - a second invocation that failed to get the lock had
+        # already deleted the directory the first build was writing into.
+        exec 9>"$lock_file"
+        if ! flock -n 9; then
+            echo "[build] ERROR: another build holds ${lock_file}; wait for it to finish" >&2
+            exit 1
+        fi
+    fi
+fi
+
+# Clean the previous build tree. Guarded so a failed cd (script dir gone,
+# BASH_SOURCE oddity) can never turn this into `rm -rf` of the caller's cwd.
+# On a self-managed Linux machine this runs INSIDE the build lock (and the
+# whole build tree stays inside it, since every child inherits descriptor 9).
+[ -n "$SCRIPT_DIR" ] && [ -d "$SCRIPT_DIR" ] || { echo "[build] ERROR: script directory not found" >&2; exit 1; }
+rm -rf "${SCRIPT_DIR:?}/build"
+
+if [[ "$(uname)" == "Linux" && "${CI:-}" != "true" && "${GITHUB_ACTION:-}" != "true" ]]; then
+    # Compile inside the systemd user scope probed above: MemoryMax bounds
+    # the total of this build tree, MemorySwapMax=0 forbids swap. The build
+    # lock (descriptor 9) is inherited and stays held while tpc runs.
+    echo "[build] whole-tree budget: systemd scope MemoryMax=${limit_mb}M, MemorySwapMax=0"
+    systemd-run --user --quiet --collect --scope \
+        -p "MemoryMax=${limit_mb}M" -p "MemorySwapMax=0" \
+        "${BUILD_CMD[@]}"
+else
+    "${BUILD_CMD[@]}"
+fi
+
+BINARY="${SCRIPT_DIR}/typephp_mcp"
+if [[ ! -x "$BINARY" ]]; then
+    echo "[build] ERROR: typephp_mcp was not produced."
+    exit 1
+fi
+file "$BINARY"
+if [[ "$(uname)" == "Darwin" ]]; then
+    otool -L "$BINARY" | sed -n '2,20p'
+fi
+echo "[build] Done: $BINARY"
diff --git a/tools/typephp-mcp/main.php b/tools/typephp-mcp/main.php
new file mode 100644
index 00000000..34f17584
--- /dev/null
+++ b/tools/typephp-mcp/main.php
@@ -0,0 +1,81 @@
+<?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 ; - POSIX also accepts :) 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/run-interpreted.php b/tools/typephp-mcp/run-interpreted.php
new file mode 100644
index 00000000..19c620b0
--- /dev/null
+++ b/tools/typephp-mcp/run-interpreted.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * Interpreted entry point for typephp-mcp.
+ *
+ * Loads the same sources the AOT build compiles (project.yml sources:
+ * main.php + src/) so the stdio smoke checks can run against plain PHP and
+ * be compared with the compiled binary - the sources are kept inside the
+ * stock-PHP/TypePHP intersection on purpose.
+ *
+ * Usage: php tools/typephp-mcp/run-interpreted.php
+ */
+
+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';
+require_once __DIR__ . '/main.php';
+
+exit(main());
diff --git a/tools/typephp-mcp/src/CodeIndex.php b/tools/typephp-mcp/src/CodeIndex.php
new file mode 100644
index 00000000..1977dd10
--- /dev/null
+++ b/tools/typephp-mcp/src/CodeIndex.php
@@ -0,0 +1,879 @@
+<?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;
+
+    /**
+     * Per-file scan cap. Files larger than this are scanned up to the cap and
+     * reported as truncated - never silently skipped, so a symbol that exists
+     * in a large file (e.g. src/Translator.php, ~400 KB) is still found and
+     * the caller learns that coverage was partial.
+     */
+    private const SCAN_FILE_MAX_BYTES = 8 * 1024 * 1024;
+
+    /**
+     * Global scan budget per call (bytes read across all files). Bounds the
+     * cost of one search on huge trees; hitting it reports coverage limits
+     * instead of scanning forever.
+     */
+    private const SCAN_BUDGET_BYTES = 64 * 1024 * 1024;
+
+    private const MAX_DEPTH = 32;
+
+    // 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 = [];
+        $unscanned = [];
+        $scannedBytes = 0;
+        foreach ($files as $file) {
+            if (count($hits) >= $limit) {
+                break;
+            }
+            if ($scannedBytes >= self::SCAN_BUDGET_BYTES) {
+                $unscanned[] = 'scan budget of ' . self::SCAN_BUDGET_BYTES . ' bytes exhausted';
+                break;
+            }
+            $read = $this->readLines($file);
+            $scannedBytes += $read['bytes'];
+            if ($read['truncated']) {
+                $unscanned[] = $this->displayPath($roots, $file, $userMode)
+                    . ' (truncated at ' . self::SCAN_FILE_MAX_BYTES . ' bytes)';
+            }
+            $lines = $read['lines'];
+            $perFile = 0;
+            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 . self::coverageNote($unscanned);
+        }
+        return TextUtil::clip(implode("\n", $hits) . self::coverageNote($unscanned), 4000);
+    }
+
+    public function getSymbol(string $name, array $dirs = []): string
+    {
+        $name = trim($name);
+        if ($name === '') {
+            return 'Invalid symbol name (expected [A-Za-z_][A-Za-z0-9_\\]* or Class::method): (empty)';
+        }
+
+        // Accept Class::method qualifiers and namespaced names (Foo\Bar).
+        $method = null;
+        $class = $name;
+        $separator = strrpos($name, '::');
+        if ($separator !== false) {
+            $class = substr($name, 0, $separator);
+            $method = substr($name, $separator + 2);
+            if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $method)) {
+                return 'Invalid method name (expected [A-Za-z_][A-Za-z0-9_]*): ' . $method;
+            }
+        }
+        $class = ltrim($class, '\\');
+        if (!preg_match('/^[A-Za-z_][A-Za-z0-9_\\\\]*$/', $class)) {
+            return 'Invalid symbol name (expected [A-Za-z_][A-Za-z0-9_\\\\]* or Class::method): ' . $name;
+        }
+        $namespace = '';
+        $shortName = $class;
+        $lastSlash = strrpos($class, '\\');
+        if ($lastSlash !== false) {
+            $namespace = substr($class, 0, $lastSlash);
+            $shortName = substr($class, $lastSlash + 1);
+        }
+
+        $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 = [];
+        $unscanned = [];
+        $scannedBytes = 0;
+        foreach ($files as $file) {
+            if (count($hits) >= 15) {
+                break;
+            }
+            if ($scannedBytes >= self::SCAN_BUDGET_BYTES) {
+                $unscanned[] = 'scan budget of ' . self::SCAN_BUDGET_BYTES . ' bytes exhausted';
+                break;
+            }
+            $read = $this->readLines($file);
+            $scannedBytes += $read['bytes'];
+            if ($read['truncated']) {
+                $unscanned[] = $this->displayPath($roots, $file, $userMode)
+                    . ' (truncated at ' . self::SCAN_FILE_MAX_BYTES . ' bytes)';
+            }
+            $lines = $read['lines'];
+            if ($method === null) {
+                $hits = array_merge($hits, $this->findDeclaration($lines, $shortName, $namespace, $file, $roots, $userMode));
+            } else {
+                $hits = array_merge($hits, $this->findClassMethod($lines, $shortName, $method, $namespace, $file, $roots, $userMode));
+            }
+            if (count($hits) >= 15) {
+                break;
+            }
+        }
+        if (count($hits) === 0) {
+            return 'No symbol found for: ' . $name
+                . ($userMode ? ' (searched provided dirs)' : ' (searched src/, examples/, tests/std/)')
+                . self::coverageNote($unscanned);
+        }
+        return TextUtil::clip(implode("\n", $hits) . self::coverageNote($unscanned), 4000);
+    }
+
+    /**
+     * Find function/class/interface/trait/enum/const declarations of a short
+     * name, honoring the file's namespace context.
+     *
+     * @param array<int, string> $lines
+     * @param array<int, string> $roots
+     * @return array<int, string>
+     */
+    private function findDeclaration(array $lines, string $shortName, string $namespace, string $file, array $roots, bool $userMode): array
+    {
+        $pattern = '/^\s*(?:(?:public|private|protected)\s+)?(?:(?:static|final|abstract|readonly)\s+)*'
+            . '(?:function|class|interface|trait|enum)\s+' . preg_quote($shortName, '/') . '\b/';
+        $constPattern = '/^\s*const\s+' . preg_quote($shortName, '/') . '\b/';
+        $namespaces = self::namespacesPerLine($lines);
+        $hits = [];
+        foreach ($lines as $index => $line) {
+            if (preg_match($pattern, $line) !== 1 && preg_match($constPattern, $line) !== 1) {
+                continue;
+            }
+            if ($namespace !== '' && $namespaces[$index] !== $namespace) {
+                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;
+            }
+        }
+        return $hits;
+    }
+
+    /**
+     * Find a method inside a class body: locate the class declaration (with
+     * namespace context) and scan its brace-delimited body for the method.
+     *
+     * @param array<int, string> $lines
+     * @param array<int, string> $roots
+     * @return array<int, string>
+     */
+    private function findClassMethod(array $lines, string $className, string $methodName, string $namespace, string $file, array $roots, bool $userMode): array
+    {
+        $classPattern = '/^\s*(?:(?:abstract|final|readonly)\s+)?class\s+' . preg_quote($className, '/') . '\b/';
+        $methodPattern = '/^\s*(?:(?:public|private|protected)\s+)?(?:(?:static|final|abstract)\s+)*function\s+' . preg_quote($methodName, '/') . '\b/';
+        $namespaces = self::namespacesPerLine($lines);
+        $hits = [];
+        foreach ($lines as $index => $line) {
+            if (preg_match($classPattern, $line) !== 1) {
+                continue;
+            }
+            if ($namespace !== '' && $namespaces[$index] !== $namespace) {
+                continue;
+            }
+            $end = self::classBodyEnd($lines, $index);
+            for ($i = $index + 1; $i < $end; $i++) {
+                if (preg_match($methodPattern, $lines[$i]) !== 1) {
+                    continue;
+                }
+                $signature = trim($lines[$i]);
+                if (strlen($signature) > 200) {
+                    $signature = TextUtil::clip($signature, 200);
+                }
+                $hits[] = $this->displayPath($roots, $file, $userMode) . ':' . ($i + 1) . '  ' . $signature
+                    . '  (in class ' . $className . ')';
+                break;
+            }
+            if (count($hits) >= 15) {
+                break;
+            }
+        }
+        return $hits;
+    }
+
+    /**
+     * Index the namespace context of every line: the file-level namespace
+     * (`namespace X;`) applies until the next namespace declaration; braced
+     * blocks (`namespace X { ... }`) apply only inside their braces. Textual
+     * heuristic - good enough for the common single-namespace layout.
+     *
+     * @param array<int, string> $lines
+     * @return array<int, string>
+     */
+    private static function namespacesPerLine(array $lines): array
+    {
+        $result = array_fill(0, count($lines), '');
+        $current = '';
+        $braceDepth = 0;
+        $blockDepth = -1;
+        foreach ($lines as $index => $line) {
+            $result[$index] = $current;
+            if (preg_match('/^\s*namespace\s+([A-Za-z_][A-Za-z0-9_\\\\]*)\s*[;{]/', $line, $matches) === 1) {
+                $current = $matches[1];
+                $blockDepth = substr(rtrim($line), -1) === '{' ? $braceDepth : -1;
+            }
+            $braceDepth += substr_count($line, '{') - substr_count($line, '}');
+            if ($blockDepth >= 0 && $braceDepth <= $blockDepth) {
+                $current = '';
+                $blockDepth = -1;
+            }
+        }
+        return $result;
+    }
+
+    /**
+     * Index of the line where the class body opened at $classIndex ends.
+     *
+     * Naive brace counting is not robust here: braces inside strings and
+     * comments unbalance the count (src/Translator.php closes "early" around
+     * line 2090 by that measure). Instead, the body ends at the next
+     * top-level declaration at or before the class's own indentation -
+     * methods and properties are always more indented, and the class's
+     * closing brace alone does not match a declaration pattern.
+     *
+     * @param array<int, string> $lines
+     */
+    private static function classBodyEnd(array $lines, int $classIndex): int
+    {
+        $classLine = $lines[$classIndex];
+        $indent = strlen($classLine) - strlen(ltrim($classLine));
+        $count = count($lines);
+        for ($i = $classIndex + 1; $i < $count; $i++) {
+            $trimmed = ltrim($lines[$i]);
+            if ($trimmed === '' || $trimmed[0] === '#' || $trimmed[0] === '/') {
+                continue;
+            }
+            $lineIndent = strlen($lines[$i]) - strlen($trimmed);
+            if ($lineIndent > $indent) {
+                continue;
+            }
+            if (preg_match('/^(?:(?:abstract|final|readonly)\s+)?(?:class|interface|trait|enum|function)\s|^namespace\s|^use\s|^const\s|^declare\s/', $trimmed) === 1) {
+                return $i;
+            }
+        }
+        return $count;
+    }
+
+    /**
+     * @param array<int, string> $unscanned
+     */
+    private static function coverageNote(array $unscanned): string
+    {
+        if ($unscanned === []) {
+            return '';
+        }
+        return "\nCoverage: " . count($unscanned) . ' item(s) not fully scanned: '
+            . implode('; ', $unscanned);
+    }
+
+    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) {
+                    $visited = [];
+                    $seenFiles = [];
+                    foreach ($this->collectDir($dir, false, 0, $visited, $seenFiles) 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 = [];
+        $visited = [];
+        $seenFiles = [];
+        foreach ($skip as $dir) {
+            foreach ($this->collectDir($dir, true, 0, $visited, $seenFiles) as $file) {
+                $files[] = $file;
+            }
+            if (count($files) >= self::MAX_FILES) {
+                break;
+            }
+        }
+        foreach ($keep as $dir) {
+            foreach ($this->collectDir($dir, false, 0, $visited, $seenFiles) as $file) {
+                $files[] = $file;
+            }
+            if (count($files) >= self::MAX_FILES) {
+                break;
+            }
+        }
+        sort($files);
+        return $files;
+    }
+
+    /**
+     * Collect .php files under $dir.
+     *
+     * $visited and $seenFiles are shared by reference across the whole
+     * traversal. Passing them by value made every sibling branch - and every
+     * additional root - start from a copy, so a symlinked alias of a directory
+     * was walked a second time and each aliased file counted twice. That
+     * duplicated results, consumed the hit limit, and made the scan budget run
+     * out before genuinely different definitions were seen.
+     *
+     * Keys are canonical paths. They are lower-cased only where the filesystem
+     * is case-insensitive (Windows), so a case-sensitive volume keeps two
+     * legitimately distinct paths apart.
+     *
+     * @param array<string, bool> $visited      canonical directories already walked
+     * @param array<string, bool> $seenFiles    canonical files already emitted
+     * @return array<int, string>
+     */
+    private function collectDir(string $dir, bool $skipPackages, int $depth, array &$visited, array &$seenFiles): array
+    {
+        $result = [];
+        if ($depth > self::MAX_DEPTH || !is_dir($dir)) {
+            return $result;
+        }
+        // Canonicalize for dedup: symlink loops and overlapping roots must not
+        // be traversed twice (the returned paths keep their original spelling
+        // so displayPath() prefix matching is unchanged).
+        $real = realpath($dir);
+        if (!is_string($real) || $real === '') {
+            return $result;
+        }
+        $key = self::pathKey($real);
+        if (isset($visited[$key])) {
+            return $result;
+        }
+        $visited[$key] = true;
+        $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, $depth + 1, $visited, $seenFiles);
+                foreach ($nested as $file) {
+                    $result[] = $file;
+                }
+            } elseif (str_ends_with($entry, '.php')) {
+                $fileReal = realpath($path);
+                $fileKey = self::pathKey(is_string($fileReal) && $fileReal !== '' ? $fileReal : $path);
+                if (isset($seenFiles[$fileKey])) {
+                    continue;
+                }
+                $seenFiles[$fileKey] = true;
+                $result[] = $path;
+            }
+        }
+        return $result;
+    }
+
+    /**
+     * Canonical key for path de-duplication. Case is folded only on
+     * case-insensitive filesystems.
+     */
+    private static function pathKey(string $path): string
+    {
+        $path = str_replace('\\', '/', $path);
+        $foldCase = stripos(PHP_OS, 'WIN') === 0 || stripos(PHP_OS, 'DARWIN') === 0;
+        return $foldCase ? strtolower($path) : $path;
+    }
+
+    /**
+     * @param array<int, string> $roots
+     * @return array<int, string>
+     */
+    private function collectStubFiles(array $roots, bool $skipPackages): array
+    {
+        $files = [];
+        $visited = [];
+        $seenFiles = [];
+        foreach ($roots as $root) {
+            foreach ($this->collectDir($root, $skipPackages, 0, $visited, $seenFiles) as $file) {
+                if (str_ends_with($file, '.stub.php')) {
+                    $files[] = $file;
+                }
+            }
+        }
+        return $files;
+    }
+
+    /**
+     * Read a file line by line in 1 MiB chunks. Files larger than
+     * SCAN_FILE_MAX_BYTES are scanned up to the cap and flagged truncated so
+     * the caller can report coverage instead of silently pretending the
+     * file does not exist (the previous 256 KiB cutoff made get_symbol miss
+     * real symbols in src/Translator.php).
+     *
+     * @return array{lines: array<int, string>, bytes: int, truncated: bool}
+     */
+    private function readLines(string $path): array
+    {
+        $handle = @fopen($path, 'rb');
+        if (!is_resource($handle)) {
+            return ['lines' => [], 'bytes' => 0, 'truncated' => false];
+        }
+        $lines = [];
+        $buffer = '';
+        $total = 0;
+        $truncated = false;
+        while (!feof($handle)) {
+            if ($total >= self::SCAN_FILE_MAX_BYTES) {
+                $truncated = true;
+                break;
+            }
+            $chunk = fread($handle, min(1048576, self::SCAN_FILE_MAX_BYTES - $total));
+            if (!is_string($chunk) || $chunk === '') {
+                break;
+            }
+            $total += strlen($chunk);
+            $buffer .= $chunk;
+            $position = strpos($buffer, "\n");
+            while ($position !== false) {
+                $lines[] = substr($buffer, 0, $position);
+                $buffer = substr($buffer, $position + 1);
+                $position = strpos($buffer, "\n");
+            }
+        }
+        fclose($handle);
+        if ($buffer !== '') {
+            $lines[] = $buffer;
+        }
+        return ['lines' => $lines, 'bytes' => $total, 'truncated' => $truncated];
+    }
+
+    /**
+     * @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)['lines'];
+        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
+    {
+        $visited = [];
+        $seenFiles = [];
+        $files = $this->collectDir($dir, $base !== '', 0, $visited, $seenFiles);
+        $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..c1e24e2d
--- /dev/null
+++ b/tools/typephp-mcp/src/CompilerOracle.php
@@ -0,0 +1,1096 @@
+<?php
+
+/**
+ * L3 compiler oracle: run `tpc --dry` on a file.
+ *
+ * The compiler is a compiled tpc binary when one is available
+ * (TYPEPHP_MCP_TPC, or tpc/tpc.exe in the repository root), otherwise the
+ * interpreted `php bin/tpc.php`. The compiled form is preferred because it
+ * needs neither a PHP interpreter nor the phpy extension.
+ *
+ * --dry only generates C++, so it validates the TypePHP subset (the #1 AI
+ * failure mode) without compiling or linking. The result names the stage that
+ * actually ran (generate) so callers do not mistake it for a compile/link
+ * check; compile and link are separate stages this tool does not run.
+ *
+ * Lifetime controls: the compiler runs as a controlled child process with a
+ * timeout, an output budget and (on POSIX) a per-process virtual-memory cap
+ * inherited by every process of the tree. On timeout the whole tree is
+ * killed (SIGKILL after a grace period, including the direct child), the
+ * temporary build directory is removed, and the call fails with a tool error
+ * so the MCP server stays responsive instead of blocking on a stuck compiler.
+ *
+ * Tool-execution failures (missing file, missing PHP, compiler could not
+ * start or did not finish) raise CompilerOracle::ToolFailure; the MCP layer
+ * maps that to isError: true. User code that fails the check is NOT a tool
+ * failure - it returns a normal structured result with diagnostics.
+ *
+ * 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.
+ */
+/**
+ * A tool-execution failure: the check could not run at all (missing input,
+ * missing toolchain, compiler timeout). The MCP layer maps this to
+ * isError: true, as opposed to a normal result reporting that user code
+ * failed the check.
+ */
+final class CompilerOracleToolFailure extends RuntimeException
+{
+}
+
+final class CompilerOracle
+{
+    public const STAGE_GENERATE = 'generate';
+
+    private const DEFAULT_TIMEOUT_SECONDS = 120;
+
+    private const DEFAULT_OUTPUT_LIMIT_BYTES = 65536;
+
+    private const DEFAULT_MEMORY_LIMIT_MB = 4096;
+
+    private const PROBE_TIMEOUT_SECONDS = 10;
+
+    /**
+     * Cached compiler command prefix, resolved once per process.
+     *
+     * @var string|null
+     */
+    private static $compilerPrefix = null;
+
+    /**
+     * @return array{code: int, output: string, timedOut: bool}
+     */
+    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) && !is_dir($resolved))) {
+            throw new CompilerOracleToolFailure(
+                'File not found: ' . $file . "\nPass an absolute path, or a path relative to the repo root."
+            );
+        }
+        // Always hand the compiler an absolute, fully resolved path: it runs
+        // with cwd set to the file's directory (see below), where a path
+        // relative to the server's cwd would no longer resolve.
+        //
+        // Realpath must come BEFORE the type check. An alias.php symlink to
+        // project.yml passes a suffix test on the given path while the
+        // compiler would open the YAML, re-entering exactly the project
+        // configuration path this tool must not take.
+        $absolute = realpath($resolved);
+        if (is_string($absolute) && $absolute !== '') {
+            $resolved = $absolute;
+        }
+        // Only single-file checks are allowed. Directory and project.yml
+        // inputs make tpc parse the project configuration, where `php-builder:
+        // {}` reaches SapiPhpBuilder even under --dry (prepare() runs before
+        // the dry-run return) and starts a real php-src build - exactly the
+        // uncontrolled make/cmake this tool must never trigger (AGENTS.md).
+        // A .php file keeps tpc in single-file mode: no YAML is parsed, and
+        // the php-builder path is unreachable (verified by interception).
+        // The check uses the resolved target, so a symlink cannot smuggle a
+        // non-PHP file past it.
+        $extension = strtolower(pathinfo($resolved, PATHINFO_EXTENSION));
+        if (!is_file($resolved) || $extension !== 'php') {
+            throw new CompilerOracleToolFailure(
+                'check_code only accepts a PHP source file, got: ' . $file . "\n"
+                . 'Pass a .php file. Directory and project.yml inputs are rejected because tpc would parse the'
+                . ' project configuration, which can start a real runtime build (php-builder) even under --dry.'
+            );
+        }
+
+        // Resolving the compiler also validates that one is reachable at all
+        // (a compiled tpc, or PHP able to run bin/tpc.php).
+        self::compilerPrefix($root);
+
+        self::ensureHostToolchain();
+
+        $buildDir = self::buildDir($resolved, $root);
+        if (!mkdir($buildDir, 0777, true)) {
+            // sys_get_temp_dir() can resolve to an unusable location when a
+            // client strips TMP/TEMP; retry under the OS temp constant.
+            $fallback = rtrim(self::fallbackTempDir(), '/\\') . '/typephp-mcp-dry-' . uniqid();
+            if (!mkdir($fallback, 0777, true)) {
+                throw new CompilerOracleToolFailure('Cannot create build directory: ' . $fallback);
+            }
+            $buildDir = $fallback;
+        }
+
+        try {
+            // Run the compiler in the directory that contains the file: tpc
+            // derives the generated output path by relativizing the source
+            // path against its own cwd, and a path it cannot relativize ends
+            // up joined onto the build directory verbatim (a drive letter
+            // inside a directory name on Windows), which then fails to write.
+            $result = self::runTpc($root, [
+                '--dry',
+                $resolved,
+                '--build-dir',
+                $buildDir,
+                '--no-color',
+                '--no-progress',
+            // null lets timeoutSeconds() consult TYPEPHP_MCP_COMPILE_TIMEOUT:
+            // passing the constant here made the documented override dead
+            // code, so the error message pointed at a setting that did
+            // nothing.
+            ], null, dirname($resolved));
+            if (self::isEnvironmentFailure($result['output'])) {
+                throw new CompilerOracleToolFailure(
+                    'The compiler could not run: ' . self::environmentFailureSummary($result['output'])
+                    . "\nThis is a tool/environment problem, not a verdict on the code being checked."
+                );
+            }
+            return self::format($resolved, $root, $result);
+        } finally {
+            self::removeDir($buildDir);
+        }
+    }
+
+    /**
+     * Run `php bin/tpc.php <args>` with a bounded lifetime and return the
+     * merged output plus exit code. Throws ToolFailure when the compiler
+     * could not be started or did not finish within the timeout.
+     *
+     * @param array<int, string> $args
+     * @return array{code: int, output: string, timedOut: bool}
+     */
+    public static function runTpc(RepoRoot $root, array $args, ?int $timeoutSeconds = null, ?string $cwd = null): array
+    {
+        return self::runProcess(
+            self::buildCommand($root, $args),
+            self::timeoutSeconds($timeoutSeconds),
+            self::outputLimit(),
+            $cwd ?? $root->path()
+        );
+    }
+
+    /**
+     * tpc --version probe used by get_index_info. Bounded like the check
+     * itself so a stuck PHP cannot hang the server.
+     */
+    public static function tpcVersion(RepoRoot $root): string
+    {
+        try {
+            $result = self::runTpc($root, ['--version', '--no-color'], self::PROBE_TIMEOUT_SECONDS);
+        } catch (CompilerOracleToolFailure $error) {
+            return 'unknown';
+        }
+        foreach (explode("\n", $result['output']) as $line) {
+            if (preg_match('/v\d+\.\d+\.\d+/', $line, $m) === 1) {
+                return $m[0];
+            }
+        }
+        return 'unknown';
+    }
+
+    /**
+     * Assemble the command line.
+     *
+     * On POSIX the compiler runs in a shell that applies `ulimit -v` before
+     * exec where the platform supports it. That is a PER-PROCESS address-space
+     * cap inherited by each descendant, not a shared budget for the tree: N
+     * children can each reach the cap. It is kept because it still stops one
+     * runaway process from taking the machine down, but it must not be
+     * described as a total cap. A real whole-tree limit needs a cgroup, which
+     * this tool does not create.
+     *
+     * macOS does not implement `ulimit -v` at all, so the shell probes for it
+     * first and, when it is unavailable, runs the compiler without a cap
+     * rather than refusing to work - refusing would make check_code unusable
+     * on that platform while protecting nothing.
+     *
+     * tpc --dry only generates C++ (no make/link), so this stage does not
+     * spawn a compiler farm. A real compile/link tier would additionally need
+     * the shared build lock and serial Make/CMake jobs (see AGENTS.md).
+     */
+    private static function buildCommand(RepoRoot $root, array $args): string
+    {
+        $parts = [self::compilerPrefix($root)];
+        foreach ($args as $arg) {
+            $parts[] = escapeshellarg($arg);
+        }
+        $command = implode(' ', $parts);
+        if (stripos(PHP_OS, 'WIN') !== 0) {
+            $limitMb = self::memoryLimitMb();
+            if ($limitMb < 1) {
+                throw new CompilerOracleToolFailure(
+                    'TYPEPHP_MCP_COMPILE_MEMORY_LIMIT_MB must be a positive number of MiB.'
+                );
+            }
+            // Probe the capability, and never claim a cap that was not
+            // applied: on macOS `ulimit -v` is accepted by the shell but
+            // ineffective, so the shell checks that the limit actually took.
+            $guard = 'if ulimit -v ' . ($limitMb * 1024) . ' 2>/dev/null && [ "$(ulimit -v)" != "unlimited" ]; then :; else echo "typephp-mcp: no per-process memory cap on this platform" >&2; fi;';
+            $command = 'bash -c ' . escapeshellarg($guard . ' exec ' . $command);
+        }
+        return $command;
+    }
+
+    /**
+     * Command prefix that runs the compiler.
+     *
+     * A compiled tpc binary is preferred when one is available (TYPEPHP_MCP_TPC,
+     * or tpc/tpc.exe in the repository root): it needs neither a PHP
+     * interpreter nor the phpy extension. That matters on Windows, where the
+     * release package ships tpc.exe while the interpreted `php bin/tpc.php`
+     * only works with phpy loaded. Falls back to the interpreted compiler.
+     */
+    private static function compilerPrefix(RepoRoot $root): string
+    {
+        if (self::$compilerPrefix !== null) {
+            return self::$compilerPrefix;
+        }
+        self::$compilerPrefix = self::resolveCompilerPrefix($root);
+        return self::$compilerPrefix;
+    }
+
+    private static function resolveCompilerPrefix(RepoRoot $root): string
+    {
+        $override = getenv('TYPEPHP_MCP_TPC');
+        if (is_string($override) && $override !== '' && is_file($override)) {
+            return escapeshellarg($override);
+        }
+        // Prefer a compiled tpc, but only when it actually runs: a binary that
+        // cannot start (missing runtime DLLs, missing mbstring) must not be
+        // preferred over a working interpreted compiler. One bounded --version
+        // probe per process decides it.
+        foreach (self::tpcBinaryNames() as $name) {
+            $candidate = $root->path() . '/' . $name;
+            if (!is_file($candidate)) {
+                continue;
+            }
+            try {
+                $probe = self::runProcess(
+                    escapeshellarg($candidate) . ' --version --no-color',
+                    self::PROBE_TIMEOUT_SECONDS,
+                    8192
+                );
+            } catch (CompilerOracleToolFailure $error) {
+                continue;
+            }
+            if ($probe['code'] === 0) {
+                return escapeshellarg($candidate);
+            }
+        }
+        $php = self::phpBinary();
+        if ($php === '') {
+            throw new CompilerOracleToolFailure(
+                "No TypePHP compiler found: no runnable tpc/tpc.exe in the repository root and no PHP on PATH.\n"
+                . 'check_code needs `tpc --dry`, or `php bin/tpc.php --dry` (which needs the phpy extension).'
+                . "\nSet TYPEPHP_MCP_TPC to a tpc binary, or TYPEPHP_MCP_PHP to a php executable."
+            );
+        }
+        return escapeshellarg($php) . ' ' . escapeshellarg($root->path() . '/bin/tpc.php');
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private static function tpcBinaryNames(): array
+    {
+        return stripos(PHP_OS, 'WIN') === 0 ? ['tpc.exe', 'tpc'] : ['tpc', 'tpc.exe'];
+    }
+
+    /**
+     * Whether any compiler invocation is possible (a compiled tpc, or PHP able
+     * to run bin/tpc.php). Lets callers skip cleanly instead of failing.
+     */
+    public static function hasCompiler(RepoRoot $root): bool
+    {
+        try {
+            self::compilerPrefix($root);
+        } catch (CompilerOracleToolFailure $error) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Execute a command with timeout, output budget and tree kill.
+     *
+     * The child's stdout/stderr are drained continuously (stored output is
+     * capped, reading is not, so the child can never block on a full pipe),
+     * and the process is reaped before returning.
+     *
+     * Windows needs more than the deadline loop: stream_select() and fread()
+     * on a process pipe may ignore the timeout there, so a silent compiler
+     * kept the loop blocked past its budget (measured on Windows PHP 8.4 ZTS:
+     * a 1 s budget returned "success" after 4.2 s, once the child finally
+     * wrote). A watchdog process kills the tree at the deadline, which closes
+     * the pipe and releases the blocked read; the elapsed time is re-checked
+     * afterwards so data that arrives late is never accepted as success.
+     *
+     * @return array{code: int, output: string, timedOut: bool}
+     */
+    private static function runProcess(string $command, int $timeoutSeconds, int $outputLimitBytes, ?string $cwd = null): array
+    {
+        $descriptors = [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']];
+        $process = proc_open($command, $descriptors, $pipes, $cwd);
+        if (!is_resource($process)) {
+            throw new CompilerOracleToolFailure('Cannot start the TypePHP compiler process.');
+        }
+        fclose($pipes[0]);
+        stream_set_blocking($pipes[1], false);
+        stream_set_blocking($pipes[2], false);
+
+        $status = @proc_get_status($process);
+        $pid = is_array($status) && isset($status['pid']) ? (int) $status['pid'] : 0;
+
+        $output = '';
+        $timedOut = false;
+        $deadline = microtime(true) + $timeoutSeconds;
+        // Windows may ignore the timeout on a blocked pipe read; the watchdog
+        // kills the tree at the deadline so that read can return.
+        $watchdog = self::armWatchdog($pid, $timeoutSeconds);
+        if (stripos(PHP_OS, 'WIN') === 0 && $watchdog === null) {
+            // Without the watchdog a silent compiler blocks the read past its
+            // budget (measured: a 1 s budget returned only after the child
+            // finished at 4.2 s). Fail fast instead of running unprotected:
+            // the just-started compiler is reaped before reporting.
+            self::terminateTree($process);
+            @fclose($pipes[1]);
+            @fclose($pipes[2]);
+            @proc_close($process);
+            throw new CompilerOracleToolFailure(
+                'The Windows compile watchdog could not be created (unwritable temporary directory or process creation failure),'
+                . ' so the compiler cannot be bounded. Fix TMP/TEMP, or raise TYPEPHP_MCP_COMPILE_TIMEOUT after making the directory writable.'
+            );
+        }
+        while (true) {
+            $remaining = $deadline - microtime(true);
+            if ($remaining <= 0) {
+                $timedOut = true;
+                break;
+            }
+            $read = [$pipes[1], $pipes[2]];
+            $write = null;
+            $except = null;
+            $ready = @stream_select($read, $write, $except, (int) ceil($remaining), (int) round(($remaining - floor($remaining)) * 1000000));
+            if ($ready === false) {
+                // select() cannot monitor these handles (Windows process pipes
+                // in some builds). Poll instead so the deadline and the
+                // watchdog still bound the wait.
+                foreach ([$pipes[1], $pipes[2]] as $stream) {
+                    $chunk = (string) @fread($stream, 65536);
+                    if ($chunk === '') {
+                        continue;
+                    }
+                    $room = $outputLimitBytes - strlen($output);
+                    if ($room > 0) {
+                        $output .= $room >= strlen($chunk) ? $chunk : substr($chunk, 0, $room);
+                    }
+                }
+                $status = proc_get_status($process);
+                if (!$status['running']) {
+                    break;
+                }
+                usleep(10000);
+                continue;
+            }
+            if ($ready > 0) {
+                foreach ($read as $stream) {
+                    $chunk = (string) @fread($stream, 65536);
+                    if ($chunk === '') {
+                        continue;
+                    }
+                    $room = $outputLimitBytes - strlen($output);
+                    if ($room > 0) {
+                        $output .= $room >= strlen($chunk) ? $chunk : substr($chunk, 0, $room);
+                    }
+                }
+            }
+            $status = proc_get_status($process);
+            if (!$status['running']) {
+                // Final drain: the child may have written between the select
+                // and the status check.
+                foreach ([$pipes[1], $pipes[2]] as $stream) {
+                    $chunk = (string) @fread($stream, 65536);
+                    if ($chunk !== '') {
+                        $room = $outputLimitBytes - strlen($output);
+                        if ($room > 0) {
+                            $output .= $room >= strlen($chunk) ? $chunk : substr($chunk, 0, $room);
+                        }
+                    }
+                }
+                break;
+            }
+        }
+
+        self::disarmWatchdog($watchdog);
+
+        // A blocked read returns only when the child writes or dies, so data
+        // can arrive long after the budget (measured: a 1 s budget "succeeded"
+        // after 4.2 s). The watchdog has killed the tree by now - never accept
+        // the late data as success.
+        if (!$timedOut && microtime(true) >= $deadline) {
+            $timedOut = true;
+        }
+
+        if ($timedOut) {
+            self::terminateTree($process);
+            // Close the output pipes before reaping: proc_close() waits for
+            // EOF on them, and a descendant that inherited the write ends
+            // would otherwise keep the server blocked forever.
+            @fclose($pipes[1]);
+            @fclose($pipes[2]);
+            @proc_close($process);
+            throw new CompilerOracleToolFailure(
+                'The TypePHP compiler did not finish within ' . $timeoutSeconds
+                . ' seconds and was killed. Raise TYPEPHP_MCP_COMPILE_TIMEOUT for huge projects.'
+            );
+        }
+        @fclose($pipes[1]);
+        @fclose($pipes[2]);
+        $code = @proc_close($process);
+        return ['code' => $code, 'output' => $output, 'timedOut' => false];
+    }
+
+    /**
+     * Kill the compiler tree at the deadline (Windows only).
+     *
+     * stream_select()/fread() on a Windows process pipe may block until the
+     * child writes or exits, ignoring the timeout, so runProcess() cannot end
+     * a silent compiler on its own. This helper sleeps past the deadline and
+     * then kills the whole tree; that closes the pipe write ends, which
+     * releases the blocked read.
+     *
+     * The helper is gated by a sentinel file: it fires only while the file
+     * still exists, and the normal path deletes it before disarming. A
+     * recycled pid is therefore never killed after a successful call, and a
+     * crash of this process still leaves the watchdog armed (the sentinel
+     * survives) - which is the right outcome for a wedged compiler.
+     *
+     * Built from cmd.exe built-ins only (ping, if, taskkill): the server runs
+     * as an AOT binary where no PHP interpreter is guaranteed to exist.
+     *
+     * @return array{process: resource, sentinel: string}|null
+     */
+    private static function armWatchdog(int $pid, int $timeoutSeconds): ?array
+    {
+        if (stripos(PHP_OS, 'WIN') !== 0 || $pid <= 0 || $timeoutSeconds <= 0) {
+            return null;
+        }
+        $sentinel = sys_get_temp_dir() . '/typephp-mcp-watchdog-' . getmypid() . '-' . mt_rand(100000, 999999);
+        if (@file_put_contents($sentinel, '1') === false) {
+            return null;
+        }
+        // ping -n N waits about N-1 seconds (the first packet is immediate),
+        // so N = timeout + 1 fires just past the deadline.
+        $command = 'ping -n ' . ($timeoutSeconds + 1) . ' 127.0.0.1 >nul & if exist '
+            . escapeshellarg($sentinel) . ' taskkill /PID ' . $pid . ' /T /F >nul 2>&1';
+        // stdio goes to NUL, not to pipes: a pipe's write ends are inherited
+        // by the ping child, and reaping the helper would then block in
+        // proc_close() until that child exits on its own (measured: 19 s).
+        $watchdog = @proc_open($command, [
+            0 => ['file', 'NUL', 'r'],
+            1 => ['file', 'NUL', 'w'],
+            2 => ['file', 'NUL', 'w'],
+        ], $pipes);
+        if (!is_resource($watchdog)) {
+            @unlink($sentinel);
+            return null;
+        }
+        return ['process' => $watchdog, 'sentinel' => $sentinel];
+    }
+
+    /**
+     * Disarm the watchdog: delete the gate first, then stop the helper tree.
+     *
+     * Removing the sentinel before terminating keeps the helper from killing
+     * anything even if it outlives this call (a ping child keeps running for
+     * a moment after cmd.exe is terminated, then sees no sentinel and does
+     * nothing). stdio is NUL rather than a pipe, so reaping the helper never
+     * waits for that child.
+     *
+     * proc_terminate() only kills the direct cmd.exe; its ping child would
+     * stay behind for the rest of the armed delay (nearly the full compile
+     * timeout, so up to two minutes per call) and would accumulate across
+     * calls. The whole tree is killed with taskkill /T before reaping.
+     *
+     * @param array{process: resource, sentinel: string}|null $watchdog
+     */
+    private static function disarmWatchdog(?array $watchdog): void
+    {
+        if ($watchdog === null) {
+            return;
+        }
+        @unlink($watchdog['sentinel']);
+        $status = @proc_get_status($watchdog['process']);
+        $pid = is_array($status) && isset($status['pid']) ? (int) $status['pid'] : 0;
+        if ($pid > 0) {
+            $discard = [];
+            @exec('taskkill /PID ' . $pid . ' /T /F 2>nul', $discard, $discardCode);
+        }
+        @proc_terminate($watchdog['process'], 9);
+        @proc_close($watchdog['process']);
+    }
+
+    /**
+     * Kill the compiler and every descendant, then wait for them to be gone.
+     *
+     * proc_terminate() only signals the direct child: on POSIX the command is
+     * started through a shell, and the compiler itself can fork (php-builder,
+     * make, cl). Killing just the parent left those running, still able to
+     * write into the build directory that check() is about to delete. So the
+     * descendants are collected first, then signalled from the leaves up, and
+     * the caller only proceeds once none of them is alive.
+     *
+     * The direct child only receives SIGTERM first: after the grace period
+     * it is SIGKILLed too. A child that ignores SIGTERM would otherwise
+     * survive this method and block the caller's proc_close() forever, and
+     * runProcess() would report "was killed" while the compiler was still
+     * running. Only when the whole tree is confirmed dead does the caller
+     * reclaim the process and delete the build directory.
+     *
+     * Windows collects the tree the same way and hands the whole thing to
+     * taskkill /T, which is done before the parent is signalled - signalling
+     * the parent first would break the parent chain the /T walk relies on.
+     */
+    private static function terminateTree(mixed $process): void
+    {
+        if (!is_resource($process)) {
+            return;
+        }
+        $status = @proc_get_status($process);
+        $pid = is_array($status) && isset($status['pid']) ? (int) $status['pid'] : 0;
+
+        if (stripos(PHP_OS, 'WIN') === 0) {
+            if ($pid > 0) {
+                $discard = [];
+                @exec('taskkill /PID ' . $pid . ' /T /F 2>nul', $discard, $discardCode);
+            }
+            @proc_terminate($process, 9);
+            self::waitForExit($process, 5);
+            return;
+        }
+
+        // Collect descendants before signalling anything: once the parent is
+        // gone the trees are reparented and can no longer be found.
+        $tree = self::descendantPids($pid);
+        @proc_terminate($process, 15);
+        foreach (array_reverse($tree) as $childPid) {
+            $discard = [];
+            @exec('kill -TERM ' . $childPid . ' 2>/dev/null', $discard, $discardCode);
+        }
+        usleep(200000);
+        // The grace period is over: SIGKILL everything still running,
+        // including the direct child - it only got SIGTERM so far.
+        foreach (array_reverse($tree) as $childPid) {
+            $discard = [];
+            @exec('kill -KILL ' . $childPid . ' 2>/dev/null', $discard, $discardCode);
+        }
+        if ($pid > 0) {
+            $discard = [];
+            @exec('kill -KILL ' . $pid . ' 2>/dev/null', $discard, $discardCode);
+        }
+        // Descendants were reparented to init, so kill -0 stops reporting
+        // them once they are gone. The direct child is OUR child: after
+        // SIGKILL it lingers as a zombie until proc_close() reaps it, so it
+        // must not go through runningPids()/waitUntilGone() - its liveness
+        // is checked via proc_get_status() in waitForExit() below.
+        $stillRunning = self::runningPids($tree);
+        if ($stillRunning !== []) {
+            self::waitUntilGone($stillRunning, 5);
+        }
+        self::waitForExit($process, 5);
+    }
+
+    /**
+     * PIDs of every live descendant of $pid (depth-first).
+     *
+     * @return array<int, int>
+     */
+    private static function descendantPids(int $pid): array
+    {
+        if ($pid <= 0) {
+            return [];
+        }
+        $parents = self::processParents();
+        $children = [];
+        foreach ($parents as $childPid => $parentPid) {
+            $children[$parentPid][] = $childPid;
+        }
+        $collected = [];
+        $queue = [$pid];
+        while ($queue !== []) {
+            $current = array_shift($queue);
+            foreach ($children[$current] ?? [] as $childPid) {
+                if (in_array($childPid, $collected, true)) {
+                    continue;
+                }
+                $collected[] = $childPid;
+                $queue[] = $childPid;
+            }
+        }
+        return $collected;
+    }
+
+    /**
+     * pid => ppid for every visible process.
+     *
+     * @return array<int, int>
+     */
+    private static function processParents(): array
+    {
+        $output = [];
+        @exec('ps -A -o pid= -o ppid= 2>/dev/null', $output);
+        $map = [];
+        foreach ($output as $line) {
+            $line = trim((string) $line);
+            if ($line === '') {
+                continue;
+            }
+            $fields = preg_split('/\s+/', $line) ?: [];
+            if (count($fields) < 2 || !is_numeric($fields[0]) || !is_numeric($fields[1])) {
+                continue;
+            }
+            $map[(int) $fields[0]] = (int) $fields[1];
+        }
+        return $map;
+    }
+
+    /**
+     * @param array<int, int> $pids
+     * @return array<int, int>
+     */
+    private static function runningPids(array $pids): array
+    {
+        $alive = [];
+        foreach ($pids as $pid) {
+            $discard = [];
+            $code = 0;
+            @exec('kill -0 ' . $pid . ' 2>/dev/null', $discard, $code);
+            if ($code === 0) {
+                $alive[] = $pid;
+            }
+        }
+        return $alive;
+    }
+
+    /**
+     * @param array<int, int> $pids
+     */
+    private static function waitUntilGone(array $pids, int $seconds): void
+    {
+        $deadline = microtime(true) + $seconds;
+        while (microtime(true) < $deadline) {
+            if (self::runningPids($pids) === []) {
+                return;
+            }
+            usleep(50000);
+        }
+    }
+
+    /**
+     * Wait for the direct child to be reaped, bounded.
+     */
+    private static function waitForExit(mixed $process, int $seconds): void
+    {
+        if (!is_resource($process)) {
+            return;
+        }
+        $deadline = microtime(true) + $seconds;
+        while (microtime(true) < $deadline) {
+            $status = @proc_get_status($process);
+            if (!is_array($status) || empty($status['running'])) {
+                return;
+            }
+            usleep(50000);
+        }
+    }
+
+    /**
+     * Signals that the generate stage never got far enough to judge the
+     * user's code: a missing embed library, a missing SDK import library, or
+     * a compiler binary that is not executable.
+     *
+     * @var array<int, string>
+     */
+    private const ENVIRONMENT_FAILURE_MARKERS = [
+        'The host PHP embed library is missing',
+        'The host PHP installation does not provide an Embed SAPI library',
+        'Neither php8ts.lib nor php8.lib found',
+        'php8embed.lib not found',
+        'No TypePHP compiler found',
+        'Permission denied',
+        'is not recognized as an internal or external command',
+        'cannot execute binary file',
+    ];
+
+    /**
+     * Whether the output describes a broken toolchain rather than invalid
+     * user code. Without this, a missing SDK came back as a normal FAILED
+     * result and the client concluded the code was at fault.
+     */
+    private static function isEnvironmentFailure(string $output): bool
+    {
+        foreach (self::ENVIRONMENT_FAILURE_MARKERS as $marker) {
+            if (stripos($output, $marker) !== false) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static function environmentFailureSummary(string $output): string
+    {
+        foreach (self::ENVIRONMENT_FAILURE_MARKERS as $marker) {
+            $position = stripos($output, $marker);
+            if ($position === false) {
+                continue;
+            }
+            $line = substr($output, $position, 300);
+            $break = strpos($line, "\n");
+            if ($break !== false) {
+                $line = substr($line, 0, $break);
+            }
+            return trim($line);
+        }
+        return 'the compiler exited before it could analyse the file';
+    }
+
+    /**
+     * Render the check result. The status line names the stage that actually
+     * ran and the diagnostic count; diagnostics carry file, line, column and
+     * severity parsed from the compiler output.
+     *
+     * @param array{code: int, output: string, timedOut: bool} $result
+     */
+    private static function format(string $file, RepoRoot $root, array $result): string
+    {
+        $diagnostics = self::parseDiagnostics($result['output'], $root);
+        $relative = $root->relativeFrom($file);
+        if ($result['code'] === 0) {
+            $lines = [
+                'OK stage=' . self::STAGE_GENERATE . ' file=' . $relative
+                . ' diagnostics=' . count($diagnostics),
+                'Note: stage=generate runs `tpc --dry` (C++ generation only). The compile and link stages are not run, so their errors are not covered.',
+            ];
+            if ($diagnostics !== []) {
+                $lines[] = 'Diagnostics:';
+                $lines = array_merge($lines, self::renderDiagnostics($diagnostics));
+            }
+            return TextUtil::clip(implode("\n", $lines), 4000);
+        }
+        $lines = [
+            'FAILED stage=' . self::STAGE_GENERATE . ' exit=' . $result['code']
+            . ' file=' . $relative . ' diagnostics=' . count($diagnostics),
+        ];
+        if ($diagnostics !== []) {
+            $lines[] = 'Diagnostics:';
+            $lines = array_merge($lines, self::renderDiagnostics($diagnostics));
+        } else {
+            $lines[] = 'Diagnostics: (none parsed; raw compiler output follows)';
+        }
+        foreach (self::keptLines($result['output']) as $line) {
+            $lines[] = $line;
+            if (count($lines) >= 40) {
+                break;
+            }
+        }
+        return TextUtil::clip(implode("\n", $lines), 4000);
+    }
+
+    /**
+     * Parse "Fatal error: <message> in <file>:<line>[:<col>]" lines.
+     *
+     * @return array<int, array{severity: string, message: string, file: string, line: int, column: int}>
+     */
+    private static function parseDiagnostics(string $output, RepoRoot $root): array
+    {
+        $diagnostics = [];
+        foreach (explode("\n", $output) as $line) {
+            $matched = preg_match(
+                '/^(Fatal error|Parse error|Compile error|Error|Warning|Notice):\s+(.+?)\s+in\s+(.+?):(\d+)(?::(\d+))?\s*$/',
+                $line,
+                $matches
+            );
+            if ($matched !== 1) {
+                continue;
+            }
+            $diagnostics[] = [
+                'severity' => self::severityFor($matches[1]),
+                'message' => $matches[2],
+                'file' => self::relativeDiagnosticPath($matches[3], $root),
+                'line' => (int) $matches[4],
+                'column' => isset($matches[5]) && $matches[5] !== '' ? (int) $matches[5] : 0,
+            ];
+        }
+        return $diagnostics;
+    }
+
+    private static function severityFor(string $label): string
+    {
+        if (str_starts_with($label, 'Warning')) {
+            return 'warning';
+        }
+        if (str_starts_with($label, 'Notice')) {
+            return 'notice';
+        }
+        return 'error';
+    }
+
+    private static function relativeDiagnosticPath(string $path, RepoRoot $root): string
+    {
+        $normalized = str_replace('\\', '/', $path);
+        $real = realpath($normalized);
+        $candidate = is_string($real) && $real !== '' ? str_replace('\\', '/', $real) : $normalized;
+        if (str_starts_with($candidate, $root->path() . '/')) {
+            return $root->relativeFrom($candidate);
+        }
+        return $candidate;
+    }
+
+    /**
+     * @param array<int, array{severity: string, message: string, file: string, line: int, column: int}> $diagnostics
+     * @return array<int, string>
+     */
+    private static function renderDiagnostics(array $diagnostics): array
+    {
+        $lines = [];
+        foreach ($diagnostics as $diagnostic) {
+            $lines[] = '- [' . $diagnostic['severity'] . '] ' . $diagnostic['file'] . ':'
+                . $diagnostic['line'] . ($diagnostic['column'] > 0 ? ':' . $diagnostic['column'] : '')
+                . ' ' . $diagnostic['message'];
+        }
+        return $lines;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private static function keptLines(string $output): array
+    {
+        $kept = [];
+        foreach (explode("\n", $output) as $line) {
+            $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) >= 20) {
+                break;
+            }
+        }
+        return $kept;
+    }
+
+    private static function timeoutSeconds(?int $explicit): int
+    {
+        if ($explicit !== null) {
+            return $explicit;
+        }
+        $override = getenv('TYPEPHP_MCP_COMPILE_TIMEOUT');
+        if (is_string($override) && $override !== '' && is_numeric($override)) {
+            $value = (int) $override;
+            if ($value > 0) {
+                return $value;
+            }
+        }
+        return self::DEFAULT_TIMEOUT_SECONDS;
+    }
+
+    private static function outputLimit(): int
+    {
+        $override = getenv('TYPEPHP_MCP_COMPILE_OUTPUT_LIMIT');
+        if (is_string($override) && $override !== '' && is_numeric($override)) {
+            $value = (int) $override;
+            if ($value > 0) {
+                return $value;
+            }
+        }
+        return self::DEFAULT_OUTPUT_LIMIT_BYTES;
+    }
+
+    private static function memoryLimitMb(): int
+    {
+        $override = getenv('TYPEPHP_MCP_COMPILE_MEMORY_LIMIT_MB');
+        if (is_string($override) && $override !== '' && is_numeric($override)) {
+            $value = (int) $override;
+            if ($value > 0) {
+                return $value;
+            }
+        }
+        return self::DEFAULT_MEMORY_LIMIT_MB;
+    }
+
+    /**
+     * 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
+     * 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;
+        }
+        try {
+            $result = self::runProcess('php -v', self::PROBE_TIMEOUT_SECONDS, 8192);
+        } catch (CompilerOracleToolFailure $error) {
+            return '';
+        }
+        if ($result['code'] === 0) {
+            return 'php';
+        }
+        return '';
+    }
+
+    /**
+     * Temporary build directory for a --dry run.
+     *
+     * It must live on the same volume as the source file: tpc derives each
+     * generated .cc path by stripping the build directory's common prefix
+     * from the source directory and appending the remainder, so a build
+     * directory on another volume (C: temp vs D: project, or the reverse)
+     * makes it append the whole absolute path instead - a path that can never
+     * be created.
+     *
+     * It must also stay OUT of the source tree: a directory created next to
+     * the file gets picked up while the compiler enumerates sources, and
+     * scanning its own generated .cc files recursed until the process died
+     * (0xC0000005 on Windows CI). The repository's build/ directory has both
+     * properties for files in the checkout; anything else falls back to the
+     * file's directory. check() removes it in a finally block.
+     */
+    private static function buildDir(string $sourceFile, RepoRoot $root): string
+    {
+        $relative = $root->relativeFrom($sourceFile);
+        if ($relative !== $sourceFile) {
+            $buildRoot = $root->path() . '/build';
+            if ((is_dir($buildRoot) || mkdir($buildRoot, 0777, true)) && is_writable($buildRoot)) {
+                return $buildRoot . '/.typephp-mcp-dry-' . uniqid();
+            }
+        }
+        $dir = dirname($sourceFile);
+        if (is_dir($dir) && is_writable($dir)) {
+            return $dir . '/.typephp-mcp-dry-' . uniqid();
+        }
+        $base = sys_get_temp_dir();
+        if (!is_dir($base) || !is_writable($base)) {
+            $base = self::fallbackTempDir();
+        }
+        return rtrim($base, '/\\') . '/typephp-mcp-dry-' . uniqid();
+    }
+
+    private static function fallbackTempDir(): string
+    {
+        return str_starts_with(PHP_OS, 'WIN') ? 'C:\\Windows\\Temp' : '/tmp';
+    }
+
+    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..1049f1e7
--- /dev/null
+++ b/tools/typephp-mcp/src/Config.php
@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * Default repository root resolution.
+ *
+ * Detection order at runtime (see RepoRoot::detect()):
+ *   1. TYPEPHP_MCP_ROOT environment variable
+ *   2. an upward walk from the current working directory
+ *   3. the source-relative default below
+ *
+ * The previous build-time constant pinned a developer machine path
+ * (D:\git\php\aot-compiler) that is meaningless on any other machine and in
+ * released artifacts. The source-relative default works whenever the server
+ * runs interpreted from a checkout, on any machine. A deployed AOT binary
+ * bakes in the path of the machine it was built on, so it MUST set
+ * TYPEPHP_MCP_ROOT; RepoRoot::detect() fails with an actionable message
+ * instead of guessing a wrong root.
+ *
+ * Distinction: the repository root found here is the TOOL RESOURCE directory
+ * (docs/, bin/tpc.php, the compiler checkout). The user's own project is a
+ * separate concept - it is discovered via TYPEPHP_MCP_PROJECT_ROOT, MCP
+ * roots, or cwd auto-detection (ProjectDetector), never from this default.
+ */
+final class Config
+{
+    /**
+     * Last-resort repository root: three levels above this file's directory
+     * (tools/typephp-mcp/src -> repo root).
+     */
+    public static function defaultRoot(): string
+    {
+        return dirname(__DIR__, 3);
+    }
+}
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..4ec6592c
--- /dev/null
+++ b/tools/typephp-mcp/src/IndexInfo.php
@@ -0,0 +1,77 @@
+<?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
+    {
+        if (CompilerOracle::phpBinary() === '') {
+            return 'unknown (no php on PATH; set TYPEPHP_MCP_PHP)';
+        }
+        return CompilerOracle::tpcVersion($root);
+    }
+
+    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..fd6eba83
--- /dev/null
+++ b/tools/typephp-mcp/src/McpServer.php
@@ -0,0 +1,519 @@
+<?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).
+ *
+ * Protocol negotiation follows the MCP versioning spec: the server answers
+ * `initialize` with a protocolVersion it actually implements. The client's
+ * requested version is echoed only when it is one of the supported versions;
+ * any other value gets the server's latest supported version instead of a
+ * pretend-agreement (echoing an arbitrary version back would claim support
+ * for a spec the server does not implement).
+ *
+ * Capability notes: `roots` is a client capability of the 2024-11-05 /
+ * 2025-03-26 revisions and was deprecated in newer revisions; it is only
+ * advertised for versions where it exists. Workspace discovery never depends
+ * on roots alone - TYPEPHP_MCP_PROJECT_ROOT and cwd-based auto-detection are
+ * always available, and roots is kept as a compatibility path.
+ */
+final class McpServer
+{
+    public const PROTOCOL_VERSION = '2024-11-05';
+
+    /**
+     * Protocol revisions this server implements. The tool capability and the
+     * JSON-RPC surface are stable across revisions, but only these versions
+     * are claimed; anything else is answered with PROTOCOL_VERSION.
+     *
+     * @var array<int, string>
+     */
+    public const SUPPORTED_PROTOCOL_VERSIONS = ['2024-11-05'];
+
+    /**
+     * Revisions where the roots capability exists (not deprecated).
+     *
+     * @var array<int, string>
+     */
+    private const ROOTS_CAPABILITY_VERSIONS = ['2024-11-05', '2025-03-26'];
+
+    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 seeds the auto-detected project dirs even when
+     * the client does not send MCP roots.
+     *
+     * Several paths are separated by ';', and on POSIX also by ':'. The colon
+     * cannot be a separator where paths carry drive letters: it is part of
+     * every "D:\..." path, so splitting on it turned the path into "D" and
+     * "\workspace\app" and the project was never detected.
+     *
+     * The decision must not depend on PHP_OS: a binary built on Linux and run
+     * on Windows has the build host's value baked in. Detect the shape of the
+     * value instead - a drive letter at the start of any segment, or a
+     * backslash separator, means this is a Windows-style list.
+     */
+    private function seedFromEnv(): void
+    {
+        $raw = getenv('TYPEPHP_MCP_PROJECT_ROOT');
+        if (!is_string($raw) || $raw === '') {
+            return;
+        }
+        $separator = stripos(PHP_OS, 'WIN') === 0 || self::looksLikeWindowsPathList($raw)
+            ? '#;#'
+            : '#[;:]#';
+        foreach (preg_split($separator, $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);
+                }
+            }
+        }
+    }
+
+    /**
+     * Whether a value looks like a Windows path list: a drive letter followed
+     * by a separator anywhere in the string, or a backslash path separator.
+     */
+    private static function looksLikeWindowsPathList(string $raw): bool
+    {
+        if (preg_match('#[A-Za-z]:[\\\\/]#', $raw) === 1) {
+            return true;
+        }
+        return str_contains($raw, '\\');
+    }
+
+    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',
+            ]]);
+        }
+        // A JSON-RPC batch (a top-level array) would have to be answered with
+        // a batch. Answer it with an explicit invalid-request error instead
+        // of dropping the line: a client that sent one would otherwise wait
+        // forever for replies it never gets. Written without array_is_list()
+        // (PHP 8.1+) to stay inside the PHP subset the compiler accepts.
+        if ($decoded !== [] && array_keys($decoded) === range(0, count($decoded) - 1)) {
+            return $this->encode(['jsonrpc' => '2.0', 'id' => null, 'error' => [
+                'code' => -32600,
+                'message' => 'Invalid Request: batch requests are not supported',
+            ]]);
+        }
+
+        $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');
+        }
+
+        // JSON-RPC notifications (no id) are never answered, even when they
+        // name a request method: a client sending tools/list without an id is
+        // not waiting for a reply, and answering would corrupt its reply
+        // stream. Notifications are neither executed nor answered.
+        if (!$hasId && in_array($method, [
+            'initialize', 'ping', 'tools/list', 'tools/call',
+            'prompts/list', 'resources/list', 'resources/templates/list',
+            'logging/setLevel',
+        ], true)) {
+            return null;
+        }
+
+        if ($method === 'initialize') {
+            $params = isset($decoded['params']) && is_array($decoded['params']) ? $decoded['params'] : [];
+            $requested = isset($params['protocolVersion']) && is_string($params['protocolVersion']) && $params['protocolVersion'] !== ''
+                ? $params['protocolVersion']
+                : '';
+            $clientCaps = isset($params['capabilities']) && is_array($params['capabilities']) ? $params['capabilities'] : [];
+            $this->clientSupportsRoots = isset($clientCaps['roots']);
+            // Negotiate per the MCP versioning spec: answer with a version we
+            // actually implement. Echo the client's version only when it is
+            // supported; never pretend to support an arbitrary newer one.
+            $negotiated = $requested !== '' && in_array($requested, self::SUPPORTED_PROTOCOL_VERSIONS, true)
+                ? $requested
+                : self::PROTOCOL_VERSION;
+            $capabilities = ['tools' => (object)[]];
+            if (in_array($negotiated, self::ROOTS_CAPABILITY_VERSIONS, true)) {
+                $capabilities['roots'] = (object)[];
+            }
+            return $this->result($id, [
+                'protocolVersion' => $negotiated,
+                'capabilities' => $capabilities,
+                '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. Workspace discovery also works without roots
+            // via TYPEPHP_MCP_PROJECT_ROOT and cwd-based detection.
+            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|float|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|float|null $id, array|object $result): string
+    {
+        return $this->encode(['jsonrpc' => '2.0', 'id' => $id, 'result' => $result]);
+    }
+
+    private function error(int|string|float|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..c9e2eae9
--- /dev/null
+++ b/tools/typephp-mcp/src/ProjectDetector.php
@@ -0,0 +1,82 @@
+<?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);
+        $unc = preg_match('#^file://(?!localhost/|/)([^/]+)#', $uri, $matches) === 1;
+        $path = preg_replace('#^file://(?:localhost)?#', '', $uri);
+        if (!is_string($path)) {
+            $path = $uri;
+        }
+        // Decode before looking for a drive letter: a client may percent-encode
+        // the colon ("file:///d%3A/git/proj"), and testing the encoded form
+        // left the leading slash in place.
+        $path = rawurldecode($path);
+        // file:///D:/x  ->  /D:/x  ->  D:/x
+        if (str_starts_with($path, '/') && preg_match('#^/[A-Za-z]:#', $path) === 1) {
+            $path = substr($path, 1);
+        }
+        $path = str_replace('\\', '/', $path);
+        // file://server/share names a UNC share; keep it in UNC form instead
+        // of a relative-looking "server/share".
+        if ($unc && !str_starts_with($path, '//')) {
+            $path = '//' . ltrim($path, '/');
+        }
+        return $path;
+    }
+}
diff --git a/tools/typephp-mcp/src/RepoRoot.php b/tools/typephp-mcp/src/RepoRoot.php
new file mode 100644
index 00000000..746e8653
--- /dev/null
+++ b/tools/typephp-mcp/src/RepoRoot.php
@@ -0,0 +1,124 @@
+<?php
+
+/**
+ * Resolves the TypePHP repository root (the tool resource directory).
+ *
+ * Detection order: TYPEPHP_MCP_ROOT env var, then an upward walk from the
+ * current working directory, then Config::defaultRoot() (source-relative;
+ * meaningless for a deployed binary, which must set TYPEPHP_MCP_ROOT).
+ */
+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[] = Config::defaultRoot();
+
+        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 (looked for docs/ + bin/tpc.php upward from the'
+            . ' working directory and from ' . Config::defaultRoot() . ').'
+            . ' 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;
+        }
+        // Require the separator boundary: a plain prefix test also accepts a
+        // sibling directory whose name merely starts with the root's
+        // (".../aot-compiler-evil" for root ".../aot-compiler"), which a
+        // symlink inside the checkout could reach.
+        $root = rtrim(str_replace('\\', '/', $this->root), '/');
+        $normalized = str_replace('\\', '/', $real);
+        if ($normalized !== $root && !str_starts_with($normalized, $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..af166c1c
--- /dev/null
+++ b/tools/typephp-mcp/src/Restrictions.php
@@ -0,0 +1,169 @@
+<?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' => [
+                    '可以继承内置类（Zend 内部类，如 ArrayObject/PDO/Exception，编译期按反射判定），也可以继承参与 AOT 编译的用户类；不能继承仅在运行时定义/加载（autoload）的用户类，否则报 "inherits from a non-existent class"。',
+                    'Native Class（#[Native]）与普通 Zend 类不能互相继承；不能继承 final 类；readonly 继承契约双向适用（Zend 父类以宿主运行时反射为准，如 BcMath\Number 是 internal readonly）。',
+                    '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/CLASS_INHERITANCE.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 (internal) classes like ArrayObject/PDO CAN be extended, and so can user classes that take part in AOT compilation; classes defined/loaded only at runtime (autoload, not compiled) cannot - the compiler reports "inherits from a non-existent class"; Native classes and plain Zend classes cannot inherit from each other; final classes cannot be extended. '
+            . '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. '
+            . 'Verified against TypePHP v0.9.5; authoritative sources: docs/zh-cn/CLASS_INHERITANCE.md, docs/zh-cn/INCOMPATIBLE_PHP_FEATURES.md, src/Translator.php.';
+    }
+}
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..65c9941d
--- /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 single PHP file 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 a path relative to the repository root. Only .php files are accepted: project.yml and directory inputs would let tpc parse the project configuration, which can start a real runtime build (php-builder) even in dry-run.',
+                        ],
+                    ],
+                    '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/McpBinaryDriver.php b/tools/typephp-mcp/tests/McpBinaryDriver.php
new file mode 100644
index 00000000..7c57bb86
--- /dev/null
+++ b/tools/typephp-mcp/tests/McpBinaryDriver.php
@@ -0,0 +1,450 @@
+<?php
+
+/**
+ * Drives a typephp-mcp executable over a real stdio session and checks the
+ * wire behavior both MCP clients and the CI stages depend on. Shared by
+ * McpBinaryTest (PHPUnit) and mcp-binary-smoke.php (standalone CI driver),
+ * so the same checks run against the AOT binary and the interpreted entry.
+ *
+ * The reply reads use deadlines: a reply must arrive while stdin is still
+ * open, which proves the server flushes per message instead of buffering
+ * until EOF (a buffering server would deadlock every real MCP client).
+ *
+ * On Windows a blocked fread() cannot be interrupted by that deadline loop
+ * (stream_set_blocking() is ignored for pipes), so each reply read is
+ * additionally guarded by an external watchdog that terminates the whole
+ * server tree shortly after the deadline. The blocked read then returns on
+ * EOF, and a wedged server can never hang the session.
+ */
+final class McpBinaryDriver
+{
+    /**
+     * Per-reply deadline. Must exceed the server's own compiler timeout
+     * (TYPEPHP_MCP_COMPILE_TIMEOUT, default 120 s) so a slow check_code is
+     * reported as its own result instead of a driver timeout.
+     */
+    private const REPLY_TIMEOUT_SECONDS = 180.0;
+
+    private const NOTIFICATION_WAIT_SECONDS = 2.0;
+
+    /**
+     * Hard ceiling for the whole session. A wedged server is killed instead of
+     * hanging the job: CI hung for over half an hour once because a stuck
+     * check_code never answered and nothing bounded the total run.
+     */
+    private const SESSION_BUDGET_SECONDS = 360.0;
+
+    /**
+     * How long after a reply deadline the Windows watchdog waits before it
+     * kills the server tree. The margin keeps the disarm (kill of the
+     * watchdog) safely ahead of the firing when a reply arrives just inside
+     * the deadline; a wedged reply therefore costs deadline + margin.
+     */
+    private const WATCHDOG_MARGIN_SECONDS = 2.0;
+
+    /**
+     * Absolute deadline for the current session, enforced by readReply().
+     *
+     * @var float|null
+     */
+    private static $deadline = null;
+
+    /**
+     * Server pid of the current session, used by the Windows watchdog to
+     * terminate the whole tree (taskkill /T) when a reply deadline passes.
+     *
+     * @var int
+     */
+    private static $serverPid = 0;
+
+    /**
+     * @param array<int, string>|string $command executable (and arguments)
+     * @return array<int, array{name: string, ok: bool, detail: string}>
+     */
+    public static function run(array|string $command, string $repoRoot, ?string $cwd = null): array
+    {
+        // Pass the full environment through, as a real MCP client does: the
+        // child needs PATH, the loader paths (LD_LIBRARY_PATH /
+        // DYLD_LIBRARY_PATH on CI), TMP/TEMP for its temporary directory,
+        // and PHP_HOME/PHPX_HOME for the compiler it spawns. TYPEPHP_MCP_ROOT
+        // is overridden so the run is pinned to this repository.
+        $environment = getenv();
+        if (!is_array($environment)) {
+            $environment = [];
+        }
+        $environment['TYPEPHP_MCP_ROOT'] = $repoRoot;
+
+        $process = proc_open(
+            $command,
+            [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']],
+            $pipes,
+            $cwd ?? $repoRoot,
+            $environment
+        );
+        if (!is_resource($process)) {
+            return [['name' => 'spawn', 'ok' => false, 'detail' => 'cannot start ' . json_encode($command)]];
+        }
+        $status = @proc_get_status($process);
+        self::$serverPid = is_array($status) && isset($status['pid']) ? (int) $status['pid'] : 0;
+
+        $checks = [];
+        self::$deadline = microtime(true) + self::SESSION_BUDGET_SECONDS;
+        try {
+            stream_set_blocking($pipes[0], false);
+            stream_set_blocking($pipes[1], false);
+
+            // 1. Handshake with an unsupported protocol version: the server
+            //    must answer with a version it actually implements.
+            self::write($pipes[0], [
+                'jsonrpc' => '2.0', 'id' => 1, 'method' => 'initialize',
+                'params' => ['protocolVersion' => '1900-01-01', 'capabilities' => new stdClass()],
+            ]);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $checks[] = self::check(
+                'handshake negotiates protocol version',
+                $reply !== null && ($reply['result']['protocolVersion'] ?? '') === '2024-11-05',
+                (string) json_encode($reply)
+            );
+
+            // 2. tools/list exposes the 12 tools.
+            self::write($pipes[0], ['jsonrpc' => '2.0', 'id' => 2, 'method' => 'tools/list']);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $tools = is_array($reply) ? ($reply['result']['tools'] ?? []) : [];
+            $checks[] = self::check('tools/list exposes 12 tools', count($tools) === 12, 'got ' . count($tools));
+
+            // 3. A tool call answers while stdin is still open (per-message flush).
+            self::write($pipes[0], [
+                'jsonrpc' => '2.0', 'id' => 3, 'method' => 'tools/call',
+                'params' => ['name' => 'list_restrictions', 'arguments' => ['topic' => 'structure']],
+            ]);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $text = is_array($reply) ? ($reply['result']['content'][0]['text'] ?? '') : '';
+            $checks[] = self::check('tools/call list_restrictions answers', str_contains($text, 'main()'), substr($text, 0, 200));
+
+            // 4. get_symbol finds a symbol in a >256 KiB file (Translator.php).
+            self::write($pipes[0], [
+                'jsonrpc' => '2.0', 'id' => 4, 'method' => 'tools/call',
+                'params' => ['name' => 'get_symbol', 'arguments' => ['name' => 'genClassPropertyInit']],
+            ]);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $text = is_array($reply) ? ($reply['result']['content'][0]['text'] ?? '') : '';
+            $checks[] = self::check(
+                'get_symbol scans large files',
+                str_contains($text, 'src/Translator.php:') && str_contains($text, 'genClassPropertyInit'),
+                substr($text, 0, 200)
+            );
+
+            // 5. check_code on a missing file is a tool error (isError: true).
+            self::write($pipes[0], [
+                'jsonrpc' => '2.0', 'id' => 5, 'method' => 'tools/call',
+                'params' => ['name' => 'check_code', 'arguments' => ['path' => 'no/such/file.php']],
+            ]);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $isError = is_array($reply) && !empty($reply['result']['isError']);
+            $checks[] = self::check('check_code missing file is a tool error', $isError, (string) json_encode($reply));
+
+            // 6. check_code on a valid file reports the generate stage.
+            self::write($pipes[0], [
+                'jsonrpc' => '2.0', 'id' => 6, 'method' => 'tools/call',
+                'params' => ['name' => 'check_code', 'arguments' => ['path' => 'examples/hello.php']],
+            ]);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $text = is_array($reply) ? ($reply['result']['content'][0]['text'] ?? '') : '';
+            // Keep enough of the compiler output to see the real failure:
+            // a 200-character excerpt hides everything past the first lines.
+            $checks[] = self::check('check_code valid file reports stage=generate', str_starts_with($text, 'OK stage=generate'), substr($text, 0, 1200));
+
+            // 7. get_index_info reports the repo root (the tpc+git path).
+            self::write($pipes[0], [
+                'jsonrpc' => '2.0', 'id' => 7, 'method' => 'tools/call',
+                'params' => ['name' => 'get_index_info', 'arguments' => []],
+            ]);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $text = is_array($reply) ? ($reply['result']['content'][0]['text'] ?? '') : '';
+            $checks[] = self::check('get_index_info reports repo root', str_contains($text, 'repo_root:'), substr($text, 0, 200));
+
+            // 8. A notification (no id) is never answered, and the server
+            // stays responsive afterwards. Send the notification and a ping
+            // back to back: the next reply must be the ping's (id 8). If the
+            // notification were answered, that stray reply (with a null or
+            // missing id) would arrive first. Probing this way avoids waiting
+            // for a "quiet window", which needs a readable-with-timeout pipe
+            // and PHP on Windows cannot provide one.
+            self::write($pipes[0], ['jsonrpc' => '2.0', 'method' => 'tools/list']);
+            self::write($pipes[0], ['jsonrpc' => '2.0', 'id' => 8, 'method' => 'ping']);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $checks[] = self::check(
+                'notification without id is not answered',
+                is_array($reply) && ($reply['id'] ?? null) === 8,
+                (string) json_encode($reply)
+            );
+            $checks[] = self::check(
+                'server responsive after notification',
+                is_array($reply) && array_key_exists('result', $reply),
+                (string) json_encode($reply)
+            );
+
+            // 9. A float id survives the round trip. Narrowing it to int made
+            // the reply unmatchable for the client that sent 1.5.
+            self::write($pipes[0], ['jsonrpc' => '2.0', 'id' => 1.5, 'method' => 'ping']);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $checks[] = self::check(
+                'float request id is preserved',
+                is_array($reply) && ($reply['id'] ?? null) === 1.5,
+                (string) json_encode($reply)
+            );
+
+            // 10. A batch line is rejected explicitly rather than dropped.
+            self::write($pipes[0], [(object) ['jsonrpc' => '2.0', 'id' => 9, 'method' => 'ping']]);
+            $reply = self::readReply($pipes[1], self::REPLY_TIMEOUT_SECONDS);
+            $checks[] = self::check(
+                'batch request is rejected explicitly',
+                is_array($reply) && ($reply['error']['code'] ?? null) === -32600,
+                (string) json_encode($reply)
+            );
+        } finally {
+            // Close the pipes first, then reap. proc_close() waits for EOF on
+            // them, so a server that stopped reading must be terminated rather
+            // than waited on - a hung server would otherwise hang CI forever.
+            @fclose($pipes[0]);
+            @fclose($pipes[1]);
+            @fclose($pipes[2]);
+            $status = @proc_get_status($process);
+            if (is_array($status) && $status['running'] && isset($status['pid'])) {
+                self::killTree((int) $status['pid']);
+            }
+            @proc_close($process);
+        }
+        return $checks;
+    }
+
+    /**
+     * Terminate the process tree. Windows needs taskkill /T because
+     * proc_terminate only signals the direct child, leaving the compiler
+     * grandchildren (and their inherited handles) alive.
+     */
+    private static function killTree(int $pid): void
+    {
+        if (stripos(PHP_OS, 'WIN') === 0) {
+            $discard = [];
+            @exec('taskkill /PID ' . $pid . ' /T /F 2>nul', $discard, $discardCode);
+            return;
+        }
+        @exec('kill -9 ' . $pid . ' 2>/dev/null', $discard, $discardCode);
+    }
+
+    private static function write($stream, array $payload): void
+    {
+        $line = json_encode($payload) . "\n";
+        $written = 0;
+        $length = strlen($line);
+        while ($written < $length) {
+            $chunk = fwrite($stream, substr($line, $written));
+            if ($chunk === false || $chunk === 0) {
+                throw new RuntimeException('cannot write to the server stdin');
+            }
+            $written += $chunk;
+        }
+    }
+
+    /**
+     * Read one newline-delimited JSON reply, waiting at most $seconds.
+     *
+     * @param resource $stream
+     * @return array<string, mixed>|null
+     */
+    private static function readReply($stream, float $seconds): ?array
+    {
+        // Blocking fgets() plus stream_set_timeout() is NOT a timeout: PHP
+        // ignores that setting on pipes, so a silent server blocked forever
+        // while the declared deadline went unused (verified with a real
+        // proc_open pipe: a reply arriving after 1.57 s was still accepted for
+        // a 1.0 s deadline).
+        //
+        // Read non-blocking in a loop against a wall-clock deadline instead.
+        // stream_set_blocking() is ignored for pipes on Windows as well, so
+        // each attempt is additionally guarded by a short, bounded sleep and
+        // the whole wait is capped by both $seconds and the session deadline.
+        // On Windows that loop still cannot interrupt a blocked fread(): the
+        // deadline checks and sleeps only run between reads. A watchdog that
+        // kills the server tree shortly after the deadline bounds even that.
+        $deadline = microtime(true) + $seconds;
+        if (self::$deadline !== null && self::$deadline < $deadline) {
+            $deadline = self::$deadline;
+        }
+        $watchdog = self::armWatchdog($deadline);
+        try {
+            stream_set_blocking($stream, false);
+            $buffer = '';
+            $emptyReads = 0;
+            while (microtime(true) < $deadline) {
+                $chunk = (string) @fread($stream, 8192);
+                if ($chunk !== '') {
+                    $emptyReads = 0;
+                    $buffer .= $chunk;
+                    $position = strpos($buffer, "\n");
+                    if ($position !== false) {
+                        // A blocked read (Windows) returns only when data
+                        // arrives, so a reply can land after the deadline -
+                        // the watchdog still has its 2 s margin at that point.
+                        // Never accept a reply that missed its deadline.
+                        if (microtime(true) >= $deadline) {
+                            return null;
+                        }
+                        $decoded = json_decode(trim(substr($buffer, 0, $position)), true);
+                        return is_array($decoded) ? $decoded : null;
+                    }
+                    continue;
+                }
+                // Only trust EOF once reads have been empty for a while: some
+                // platforms report it prematurely right after the child starts.
+                $emptyReads++;
+                if ($emptyReads > 100 && feof($stream)) {
+                    return null;
+                }
+                usleep(20000);
+            }
+            return null;
+        } finally {
+            self::disarmWatchdog($watchdog);
+        }
+    }
+
+    /**
+     * Arm the Windows watchdog for one reply read.
+     *
+     * On Windows a blocked fread() returns only when the pipe has data or
+     * its write end closes, so an unresponsive server would block the read
+     * forever no matter what deadlines the loop declares. A detached helper
+     * process waits until shortly after the deadline and then terminates the
+     * WHOLE server tree (taskkill /T /F): the closed write ends release the
+     * blocked read, and no orphaned compiler grandchild can outlive the
+     * session. POSIX needs none of this - its read loop is genuinely
+     * non-blocking - and returns null.
+     *
+     * @return array{process: resource}|null
+     */
+    private static function armWatchdog(float $deadline): ?array
+    {
+        if (stripos(PHP_OS, 'WIN') !== 0 || self::$serverPid <= 0) {
+            return null;
+        }
+        $delaySeconds = ($deadline - microtime(true)) + self::WATCHDOG_MARGIN_SECONDS;
+        if ($delaySeconds <= 0) {
+            return null;
+        }
+        // Fire-and-forget helper: sleeps, then kills the tree. Killing a pid
+        // that has since exited (or was reused) is the same residual risk the
+        // session-end killTree already carries, and the helper is disarmed
+        // microseconds after a timely reply.
+        $code = sprintf(
+            'usleep(%d); exec("taskkill /PID %d /T /F 2>nul");',
+            (int) round($delaySeconds * 1000000),
+            self::$serverPid
+        );
+        $pipes = [];
+        $watchdog = @proc_open([PHP_BINARY, '-r', $code], [1 => ['pipe', 'w'], 2 => ['pipe', 'w']], $pipes);
+        if (!is_resource($watchdog)) {
+            return null;
+        }
+        foreach ($pipes as $pipe) {
+            @fclose($pipe);
+        }
+        return ['process' => $watchdog];
+    }
+
+    /**
+     * Disarm the watchdog: kill it before it can fire, then reap it.
+     *
+     * @param array{process: resource}|null $watchdog
+     */
+    private static function disarmWatchdog(?array $watchdog): void
+    {
+        if ($watchdog === null) {
+            return;
+        }
+        @proc_terminate($watchdog['process'], 9);
+        @proc_close($watchdog['process']);
+    }
+
+    /**
+     * Deadline probe for a service that stays alive but never replies.
+     *
+     * Proves the reply deadline is actually enforced - a normal session
+     * passing proves nothing about it, because every reply there arrives
+     * immediately. On Windows the watchdog must also have terminated the
+     * whole tree by the time the read gives up; on POSIX the deadline comes
+     * from the non-blocking read loop and the stub is cleaned up here.
+     *
+     * @param array<int, string>|string $command
+     * @return array{gotReply: bool, elapsed: float, treeKilled: bool}
+     */
+    public static function runSilentServerProbe(array|string $command, float $replyTimeout): array
+    {
+        $process = proc_open(
+            $command,
+            [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']],
+            $pipes
+        );
+        if (!is_resource($process)) {
+            return ['gotReply' => true, 'elapsed' => 0.0, 'treeKilled' => false];
+        }
+        $status = @proc_get_status($process);
+        self::$serverPid = is_array($status) && isset($status['pid']) ? (int) $status['pid'] : 0;
+        self::$deadline = microtime(true) + $replyTimeout + self::WATCHDOG_MARGIN_SECONDS + 30.0;
+        $started = microtime(true);
+        $gotReply = false;
+        try {
+            // A request the stub never answers; the write itself cannot block
+            // because the line is far smaller than the pipe buffer.
+            self::write($pipes[0], [
+                'jsonrpc' => '2.0', 'id' => 1, 'method' => 'initialize',
+                'params' => ['protocolVersion' => '1900-01-01', 'capabilities' => new stdClass()],
+            ]);
+            $gotReply = self::readReply($pipes[1], $replyTimeout) !== null;
+        } finally {
+            @fclose($pipes[0]);
+            @fclose($pipes[1]);
+            @fclose($pipes[2]);
+            $treeKilled = false;
+            // On Windows the watchdog has already fired (the blocked read can
+            // only have ended through the kill); on POSIX nothing killed the
+            // stub, so the deadline must have done the work instead.
+            if (stripos(PHP_OS, 'WIN') === 0 && self::$serverPid > 0) {
+                $pollDeadline = microtime(true) + 2.0;
+                while (microtime(true) < $pollDeadline) {
+                    $status = @proc_get_status($process);
+                    if (!is_array($status) || empty($status['running'])) {
+                        $treeKilled = true;
+                        break;
+                    }
+                    usleep(50000);
+                }
+            }
+            if (!$treeKilled) {
+                $status = @proc_get_status($process);
+                if (is_array($status) && $status['running'] && isset($status['pid'])) {
+                    self::killTree((int) $status['pid']);
+                }
+            }
+            @proc_close($process);
+        }
+        return [
+            'gotReply' => $gotReply,
+            'elapsed' => microtime(true) - $started,
+            'treeKilled' => $treeKilled,
+        ];
+    }
+
+    /**
+     * @param array<string, mixed>|null $reply
+     * @return array{name: string, ok: bool, detail: string}
+     */
+    private static function check(string $name, bool $ok, string $detail): array
+    {
+        // Report progress immediately: if a later step wedges the process,
+        // the job log still shows which checks completed and which one hung.
+        fwrite(STDERR, sprintf("[driver] %s %s\n", $ok ? 'ok  ' : 'fail', $name));
+        return ['name' => $name, 'ok' => $ok, 'detail' => $detail];
+    }
+}
diff --git a/tools/typephp-mcp/tests/McpBinaryTest.php b/tools/typephp-mcp/tests/McpBinaryTest.php
new file mode 100644
index 00000000..3075cc2f
--- /dev/null
+++ b/tools/typephp-mcp/tests/McpBinaryTest.php
@@ -0,0 +1,157 @@
+<?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__ . '/McpBinaryDriver.php';
+
+/**
+ * Integration test: drives the compiled typephp_mcp binary over a real stdio
+ * session (shared wire checks with the CI smoke driver). Skips when the
+ * binary has not been built unless TYPEPHP_MCP_REQUIRE_BINARY=1, which CI
+ * sets so a missing artifact fails the stage instead of silently passing.
+ */
+final class McpBinaryTest extends TestCase
+{
+    private const REPO_ROOT = __DIR__ . '/../../..';
+
+    public function testStdioMcpSession(): void
+    {
+        $binary = self::binaryPath();
+        if ($binary === null) {
+            if (getenv('TYPEPHP_MCP_REQUIRE_BINARY') === '1') {
+                self::fail('typephp_mcp binary missing; CI must build it (tools/typephp-mcp/build.sh or build.bat)');
+            }
+            self::markTestSkipped('typephp_mcp binary not built; run tools/typephp-mcp/build.sh (Unix) or build.bat (Windows)');
+        }
+
+        $checks = McpBinaryDriver::run($binary, self::repoRoot(), null);
+        self::assertNotEmpty($checks);
+        foreach ($checks as $check) {
+            self::assertTrue($check['ok'], $check['name'] . ': ' . $check['detail']);
+        }
+    }
+
+    public function testStdioSessionFromOutsideRepo(): void
+    {
+        // The server must not depend on the dev machine's checkout location:
+        // launch it from a temporary directory outside the repository.
+        $binary = self::binaryPath();
+        if ($binary === null) {
+            if (getenv('TYPEPHP_MCP_REQUIRE_BINARY') === '1') {
+                self::fail('typephp_mcp binary missing; CI must build it (tools/typephp-mcp/build.sh or build.bat)');
+            }
+            self::markTestSkipped('typephp_mcp binary not built; run tools/typephp-mcp/build.sh (Unix) or build.bat (Windows)');
+        }
+
+        $dir = sys_get_temp_dir() . '/typephp-mcp-outside-' . bin2hex(random_bytes(4));
+        self::assertTrue(mkdir($dir, 0777, true));
+        try {
+            $checks = McpBinaryDriver::run($binary, self::repoRoot(), $dir);
+            self::assertNotEmpty($checks);
+            foreach ($checks as $check) {
+                self::assertTrue($check['ok'], $check['name'] . ': ' . $check['detail']);
+            }
+        } finally {
+            self::removeDir($dir);
+        }
+    }
+
+    public function testInterpretedEntryMatchesAotChecks(): void
+    {
+        // The same wire checks against the interpreted entry: the sources are
+        // kept in the stock-PHP/TypePHP intersection, so both runtimes must
+        // answer identically.
+        $php = getenv('TYPEPHP_MCP_PHP');
+        if (!is_string($php) || $php === '' || !is_file($php)) {
+            $php = 'php';
+        }
+        $command = [$php, dirname(__DIR__) . '/run-interpreted.php'];
+        $checks = McpBinaryDriver::run($command, self::repoRoot(), null);
+        self::assertNotEmpty($checks);
+        foreach ($checks as $check) {
+            self::assertTrue($check['ok'], $check['name'] . ': ' . $check['detail']);
+        }
+    }
+
+    public function testSilentServerDeadlineIsEnforced(): void
+    {
+        // A service that stays alive but never replies must not wedge the
+        // driver. A normal session passing proves nothing about the reply
+        // deadline - every reply there arrives immediately - so this probe
+        // runs a stand-in that holds the pipe open and never writes. On
+        // Windows the watchdog must also have terminated the whole tree by
+        // the time the read gives up; on POSIX the non-blocking loop ends the
+        // read at the deadline and the probe cleans the stub up itself.
+        $probe = McpBinaryDriver::runSilentServerProbe(
+            [PHP_BINARY, '-r', 'while (true) { usleep(50000); }'],
+            1.0
+        );
+        self::assertFalse($probe['gotReply'], 'a silent server must not produce a reply');
+        // reply deadline (1.0) + watchdog margin (2.0) + CI slack.
+        self::assertLessThan(4.5, $probe['elapsed'], 'the reply deadline was not enforced');
+        if (stripos(PHP_OS, 'WIN') === 0) {
+            self::assertTrue($probe['treeKilled'], 'the watchdog must terminate the whole silent tree');
+        }
+    }
+
+    public function testLateReplyIsRejected(): void
+    {
+        // A reply that arrives after the deadline must be rejected even while
+        // the watchdog margin is still open: on Windows the blocked read
+        // returns the moment the data arrives, so the deadline has to be
+        // re-checked before the payload is accepted. A fully silent server
+        // alone would not catch this - the reply here is valid, only late.
+        $probe = McpBinaryDriver::runSilentServerProbe(
+            [PHP_BINARY, '-r', 'usleep(1600000); echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}\n";'],
+            0.3
+        );
+        self::assertFalse($probe['gotReply'], 'a reply after the deadline must be rejected');
+    }
+    private static function binaryPath(): ?string
+    {
+        $override = getenv('TYPEPHP_MCP_BINARY');
+        if (is_string($override) && $override !== '' && is_file($override)) {
+            return $override;
+        }
+        $dir = dirname(__DIR__);
+        foreach (['typephp_mcp.exe', 'typephp_mcp'] as $name) {
+            $path = $dir . '/' . $name;
+            if (is_file($path)) {
+                return $path;
+            }
+        }
+        return null;
+    }
+
+    private static function repoRoot(): string
+    {
+        $root = getenv('TYPEPHP_MCP_ROOT');
+        if (is_string($root) && $root !== '') {
+            return str_replace('\\', '/', $root);
+        }
+        return str_replace('\\', '/', self::REPO_ROOT);
+    }
+
+    private static 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)) {
+                self::removeDir($path);
+            } else {
+                @unlink($path);
+            }
+        }
+        @rmdir($dir);
+    }
+}
diff --git a/tools/typephp-mcp/tests/McpServerTest.php b/tools/typephp-mcp/tests/McpServerTest.php
new file mode 100644
index 00000000..2b3ccd35
--- /dev/null
+++ b/tools/typephp-mcp/tests/McpServerTest.php
@@ -0,0 +1,1308 @@
+<?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 testFloatRequestIdsArePreserved(): void
+    {
+        // JSON-RPC allows a Number id, floats included. Narrowing the id to
+        // int truncated 1.5 to 1, so the client could not match the reply to
+        // its request.
+        $raw = (string) $this->server->handleLine('{"jsonrpc":"2.0","id":1.5,"method":"ping"}');
+        self::assertStringContainsString('"id":1.5', $raw);
+
+        $raw = (string) $this->server->handleLine(
+            '{"jsonrpc":"2.0","id":2.25,"method":"tools/call","params":{"name":"list_restrictions","arguments":{"topic":"build"}}}'
+        );
+        self::assertStringContainsString('"id":2.25', $raw);
+    }
+
+    public function testBatchRequestIsRejectedExplicitly(): void
+    {
+        // Dropping a batch line silently would leave the client waiting for
+        // replies that never come; answer with an invalid-request error.
+        $raw = (string) $this->server->handleLine('[{"jsonrpc":"2.0","id":1,"method":"ping"}]');
+        $reply = json_decode($raw, true);
+        self::assertSame(-32600, $reply['error']['code']);
+        self::assertStringContainsString('batch', $reply['error']['message']);
+    }
+
+    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 testInitializeNegotiatesProtocolVersion(): void
+    {
+        // The server answers with a version it actually implements. A
+        // supported version is echoed; an unsupported one is answered with
+        // the server's latest supported version instead of a pretend-agreement.
+        $reply = $this->request('{"jsonrpc":"2.0","id":6,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"1"}}}');
+        self::assertSame('2024-11-05', $reply['result']['protocolVersion']);
+
+        $reply = $this->request('{"jsonrpc":"2.0","id":7,"method":"initialize","params":{"protocolVersion":"1900-01-01","capabilities":{},"clientInfo":{"name":"x","version":"1"}}}');
+        self::assertSame('2024-11-05', $reply['result']['protocolVersion']);
+        self::assertSame([], (array) $reply['result']['capabilities']['tools']);
+        // roots is a client capability of the supported revision only.
+        self::assertArrayHasKey('roots', $reply['result']['capabilities']);
+
+        // No version offered by the client -> fall back to ours.
+        $reply = $this->request('{"jsonrpc":"2.0","id":8,"method":"initialize","params":{}}');
+        self::assertSame('2024-11-05', $reply['result']['protocolVersion']);
+
+        // Garbage params must not break the handshake.
+        $reply = $this->request('{"jsonrpc":"2.0","id":9,"method":"initialize","params":"not-an-object"}');
+        self::assertSame('2024-11-05', $reply['result']['protocolVersion']);
+    }
+
+    public function testRequestNotificationsAreNotAnswered(): void
+    {
+        // A request method sent without an id is a JSON-RPC notification and
+        // must never be answered - not even with an error.
+        self::assertNull($this->server->handleLine('{"jsonrpc":"2.0","method":"tools/list"}'));
+        self::assertNull($this->server->handleLine('{"jsonrpc":"2.0","method":"ping"}'));
+        self::assertNull($this->server->handleLine('{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_topics","arguments":{}}}'));
+    }
+
+    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::hasCompiler($this->root)) {
+            self::markTestSkipped('no TypePHP compiler available (no tpc binary and no php on PATH)');
+        }
+        $text = $this->toolText('check_code', ['path' => 'examples/hello.php']);
+        self::assertStringStartsWith('OK stage=generate', $text);
+        self::assertStringContainsString('compile and link stages are not run', $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::hasCompiler($this->root)) {
+            self::markTestSkipped('no TypePHP compiler available (no tpc binary and no php 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 testCheckCodeRejectsNonPhpInputs(): void
+    {
+        // tpc parses project configuration for directory and project.yml
+        // inputs, and a `php-builder: {}` entry reaches SapiPhpBuilder even
+        // under --dry (prepare() runs before the dry-run return), starting a
+        // real php-src build on the user's machine. check_code must accept
+        // only .php files, which keep tpc in single-file mode: no YAML is
+        // parsed and the builder path is unreachable.
+        foreach (['project.yml', 'examples/qt-taskboard'] as $path) {
+            $reply = $this->request((string) json_encode([
+                'jsonrpc' => '2.0',
+                'id' => 1,
+                'method' => 'tools/call',
+                'params' => ['name' => 'check_code', 'arguments' => ['path' => $path]],
+            ]));
+            self::assertTrue($reply['result']['isError'] ?? false, "$path must be a tool error");
+            self::assertStringContainsString(
+                'only accepts a PHP source file',
+                (string) ($reply['result']['content'][0]['text'] ?? ''),
+                "$path rejection must explain why"
+            );
+        }
+    }
+    public function testCheckCodeResolvesSymlinksBeforeTheTypeCheck(): void
+    {
+        // The suffix check must run on the resolved target. An alias.php
+        // symlink to project.yml passes a check on the given path while the
+        // compiler opens the YAML, re-entering the project-configuration path
+        // (php-builder) this tool must not take. The rejection has to happen
+        // before the compiler is started at all.
+        $sandbox = $this->makeSandbox();
+        $yaml = $sandbox . '/project.yml';
+        file_put_contents($yaml, "php-builder: {}\n");
+        $real = $sandbox . '/real.php';
+        file_put_contents($real, "<?php\nfunction main(): int\n{\n    return 0;\n}\n");
+        $aliasYaml = $sandbox . '/alias.php';
+        $aliasPhp = $sandbox . '/good.php';
+        if (!@symlink($yaml, $aliasYaml) || !@symlink($real, $aliasPhp)) {
+            $this->removeDir($sandbox);
+            self::markTestSkipped('cannot create symlinks in this environment');
+        }
+
+        $log = $sandbox . '/calls.log';
+        $previousLog = getenv('TYPEPHP_FAKE_CALL_LOG');
+        putenv('TYPEPHP_FAKE_CALL_LOG=' . $log);
+        try {
+            $this->withFakeCompiler('record-call', function (McpServer $server) use ($aliasYaml, $aliasPhp, $log): array {
+                $reply = json_decode((string) $server->handleLine((string) json_encode([
+                    'jsonrpc' => '2.0',
+                    'id' => 1,
+                    'method' => 'tools/call',
+                    'params' => ['name' => 'check_code', 'arguments' => ['path' => $aliasYaml]],
+                ])), true);
+                self::assertTrue($reply['result']['isError'] ?? false, 'a .php symlink to YAML must be rejected');
+                self::assertStringContainsString(
+                    'only accepts a PHP source file',
+                    (string) ($reply['result']['content'][0]['text'] ?? '')
+                );
+                self::assertFileDoesNotExist($log, 'the compiler was started for a symlink to YAML');
+
+                $reply = json_decode((string) $server->handleLine((string) json_encode([
+                    'jsonrpc' => '2.0',
+                    'id' => 2,
+                    'method' => 'tools/call',
+                    'params' => ['name' => 'check_code', 'arguments' => ['path' => $aliasPhp]],
+                ])), true);
+                self::assertStringStartsWith(
+                    'OK stage=generate',
+                    (string) ($reply['result']['content'][0]['text'] ?? ''),
+                    'a .php symlink to a real PHP file must be checked normally'
+                );
+                // The compiler receives the resolved target, not the alias.
+                $calls = is_file($log) ? trim((string) file_get_contents($log)) : '';
+                self::assertStringContainsString('real.php', $calls, 'the compiler must see the resolved path');
+                self::assertStringNotContainsString('good.php', $calls);
+                return [];
+            });
+        } finally {
+            if ($previousLog === false) { putenv('TYPEPHP_FAKE_CALL_LOG'); } else { putenv('TYPEPHP_FAKE_CALL_LOG=' . $previousLog); }
+            $this->removeDir($sandbox);
+        }
+    }
+    public function testCheckCodeMissingFileIsAToolError(): void
+    {
+        // A missing path is a tool-execution failure, not a check result:
+        // the MCP reply must carry isError: true so clients can tell the
+        // difference between "your code failed" and "the tool could not run".
+        $reply = $this->request((string) json_encode([
+            'jsonrpc' => '2.0',
+            'id' => 1,
+            'method' => 'tools/call',
+            'params' => ['name' => 'check_code', 'arguments' => ['path' => 'no/such/file.php']],
+        ]));
+        self::assertTrue($reply['result']['isError'] ?? false);
+        self::assertStringContainsString('File not found', $reply['result']['content'][0]['text']);
+    }
+
+    public function testListRestrictionsCoversMainSignatureAndScope(): void
+    {
+        $text = $this->toolText('list_restrictions', ['topic' => 'structure']);
+        self::assertStringContainsString('main()', $text);
+        self::assertStringContainsString('全局作用域', $text);
+        self::assertStringContainsString('[structure]', $text);
+
+        // Inheritance rules must match the compiler's real behavior (v0.9.5):
+        // Zend internal classes CAN be inherited; only runtime-only (autoload)
+        // user classes cannot. See tests/compiler/class/class_extends.phpt.
+        $text = $this->toolText('list_restrictions', ['topic' => 'objects']);
+        self::assertStringContainsString('可以继承内置类', $text);
+        self::assertStringContainsString('autoload', $text);
+        self::assertStringContainsString('Native', $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 testGetSymbolScansLargeFiles(): void
+    {
+        // src/Translator.php is ~400 KB, far above the old 256 KiB silent
+        // cutoff. The symbol must be found, and no coverage truncation may
+        // be reported for it.
+        $text = $this->toolText('get_symbol', ['name' => 'genClassPropertyInit']);
+        self::assertStringContainsString('src/Translator.php:', $text);
+        self::assertStringContainsString('genClassPropertyInit', $text);
+        self::assertStringNotContainsString('truncated', $text);
+    }
+
+    public function testGetSymbolSupportsNamespaceAndClassMethod(): void
+    {
+        // Full namespace path resolves against the file's namespace context.
+        $text = $this->toolText('get_symbol', ['name' => 'TypePhp\Translator']);
+        self::assertStringContainsString('class Translator', $text);
+        self::assertStringContainsString('src/Translator.php:', $text);
+
+        // Class::method finds the method inside the class body.
+        $text = $this->toolText('get_symbol', ['name' => 'Translator::genClassPropertyInit']);
+        self::assertStringContainsString('function genClassPropertyInit', $text);
+        self::assertStringContainsString('in class Translator', $text);
+
+        $text = $this->toolText('get_symbol', ['name' => 'Translator::no_such_method_xyz']);
+        self::assertStringContainsString('No symbol found', $text);
+    }
+
+    public function testGetSymbolReturnsDuplicateDefinitions(): void
+    {
+        // The same short name defined in several files yields one hit per
+        // definition (duplicate symbols are not silently deduped).
+        $text = $this->toolText('get_symbol', ['name' => 'main']);
+        $lines = explode("\n", $text);
+        $declarationLines = array_values(array_filter($lines, static function (string $line): bool {
+            return str_contains($line, 'function main');
+        }));
+        self::assertGreaterThanOrEqual(2, count($declarationLines), $text);
+    }
+
+    public function testGetSymbolScansLargeSyntheticFile(): void
+    {
+        // A file above the old cutoff, passed via dirs, must be scanned.
+        $dir = sys_get_temp_dir() . '/typephp-mcp-big-' . bin2hex(random_bytes(4));
+        self::assertNotFalse(mkdir($dir, 0777, true));
+        $file = $dir . '/Big.php';
+        try {
+            $filler = "<?php\n// " . str_repeat('x', 100) . "\n";
+            self::assertNotFalse(file_put_contents($file, $filler . str_repeat($filler, 3000) . "<?php\nfunction bigFileSymbol() {}\n"));
+            $text = $this->toolText('get_symbol', ['name' => 'bigFileSymbol', 'dirs' => [$dir]]);
+            self::assertStringContainsString('bigFileSymbol', $text);
+            self::assertStringNotContainsString('No symbol found', $text);
+        } finally {
+            self::removeDir($dir);
+        }
+    }
+
+    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));
+    }
+
+    /**
+     * Write a stand-in compiler that behaves according to
+     * TYPEPHP_FAKE_TPC_MODE ("env-missing", "user-code-error" or "slow"), so
+     * the failure-classification paths can be exercised without a real SDK.
+     * Returns the executable to point TYPEPHP_MCP_TPC at.
+     */
+    private function makeFakeCompiler(string $dir): string
+    {
+        $script = <<<'PHP'
+<?php
+$mode = getenv('TYPEPHP_FAKE_TPC_MODE');
+if (!is_string($mode) || $mode === '') { $mode = 'env-missing'; }
+if (in_array('--version', $argv, true)) { echo "TypePHP Compiler (AOT) v9.9.9\n"; exit(0); }
+switch ($mode) {
+    case 'env-missing':
+        fwrite(STDERR, "Fatal error: The host PHP embed library is missing: fake detail\n");
+        exit(1);
+    case 'user-code-error':
+        fwrite(STDERR, "Fatal error: Unsupported statement: Stmt_Echo in $argv[2]:2\n");
+        exit(1);
+    case 'record-call':
+        // Records every real invocation so a test can prove the
+        // compiler was never started for a rejected path.
+        file_put_contents((string) getenv('TYPEPHP_FAKE_CALL_LOG'), json_encode(array_slice($argv, 1)) . "\n", FILE_APPEND);
+        echo "Dry run completed\n";
+        exit(0);
+    case 'slow':
+        sleep(30);
+        echo "Dry run completed\n";
+        exit(0);
+    case 'silent-then-finish':
+        // Silent past the budget, then reports success. Stand-in for Windows
+        // pipes, where a blocked read ignores the timeout: the late "success"
+        // must never be accepted.
+        usleep(4000000);
+        echo "Dry run completed\n";
+        exit(0);
+}
+exit(0);
+PHP;
+        $this->sandboxWrite($dir, 'fake-tpc.php', $script);
+        if (stripos(PHP_OS, 'WIN') === 0) {
+            $this->sandboxWrite($dir, 'fake-tpc.bat', "@echo off\r\nphp \"%~dp0fake-tpc.php\" %*\r\n");
+            return $dir . '/fake-tpc.bat';
+        }
+        $this->sandboxWrite($dir, 'fake-tpc.sh', "#!/usr/bin/env bash\nexec php \"\$(dirname \"\$0\")/fake-tpc.php\" \"\$@\"\n");
+        @chmod($dir . '/fake-tpc.sh', 0755);
+        return $dir . '/fake-tpc.sh';
+    }
+
+    /**
+     * Run a tool call with TYPEPHP_MCP_TPC pointed at the stand-in compiler.
+     *
+     * @return array<string, mixed>
+     */
+    private function withFakeCompiler(string $mode, callable $call): array
+    {
+        $sandbox = $this->makeSandbox();
+        $previousTpc = getenv('TYPEPHP_MCP_TPC');
+        $previousMode = getenv('TYPEPHP_FAKE_TPC_MODE');
+        try {
+            putenv('TYPEPHP_MCP_TPC=' . $this->makeFakeCompiler($sandbox));
+            putenv('TYPEPHP_FAKE_TPC_MODE=' . $mode);
+            // Force a fresh resolution: the compiler prefix is cached per
+            // process, and other tests already resolved the real one.
+            // (setAccessible() is a no-op since PHP 8.1 and deprecated in 8.5.)
+            (new ReflectionProperty(CompilerOracle::class, 'compilerPrefix'))->setValue(null, null);
+
+            return $call(new McpServer($this->root));
+        } finally {
+            if ($previousTpc === false) { putenv('TYPEPHP_MCP_TPC'); } else { putenv('TYPEPHP_MCP_TPC=' . $previousTpc); }
+            if ($previousMode === false) { putenv('TYPEPHP_FAKE_TPC_MODE'); } else { putenv('TYPEPHP_FAKE_TPC_MODE=' . $previousMode); }
+            (new ReflectionProperty(CompilerOracle::class, 'compilerPrefix'))->setValue(null, null);
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testMissingSdkIsReportedAsToolError(): void
+    {
+        $reply = $this->withFakeCompiler('env-missing', function (McpServer $server): array {
+            $raw = (string) $server->handleLine((string) json_encode([
+                'jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/call',
+                'params' => ['name' => 'check_code', 'arguments' => ['path' => 'examples/hello.php']],
+            ]));
+            return (array) json_decode($raw, true);
+        });
+        self::assertTrue($reply['result']['isError'] ?? false, 'a missing SDK must not look like a code verdict');
+        self::assertStringContainsString('embed library is missing', $reply['result']['content'][0]['text']);
+    }
+
+    public function testUserCodeErrorStaysANormalResult(): void
+    {
+        $reply = $this->withFakeCompiler('user-code-error', function (McpServer $server): array {
+            $raw = (string) $server->handleLine((string) json_encode([
+                'jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/call',
+                'params' => ['name' => 'check_code', 'arguments' => ['path' => 'examples/hello.php']],
+            ]));
+            return (array) json_decode($raw, true);
+        });
+        self::assertFalse($reply['result']['isError'] ?? false, 'invalid user code is a check result, not a tool error');
+        self::assertStringStartsWith('FAILED stage=generate', $reply['result']['content'][0]['text']);
+        self::assertStringContainsString('Unsupported statement', $reply['result']['content'][0]['text']);
+    }
+
+    public function testCompileTimeoutHonoursTheEnvironmentOverride(): void
+    {
+        $previous = getenv('TYPEPHP_MCP_COMPILE_TIMEOUT');
+        try {
+            putenv('TYPEPHP_MCP_COMPILE_TIMEOUT=2');
+            $started = microtime(true);
+            $reply = $this->withFakeCompiler('slow', function (McpServer $server): array {
+                $raw = (string) $server->handleLine((string) json_encode([
+                    'jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/call',
+                    'params' => ['name' => 'check_code', 'arguments' => ['path' => 'examples/hello.php']],
+                ]));
+                return (array) json_decode($raw, true);
+            });
+            $elapsed = microtime(true) - $started;
+            self::assertTrue($reply['result']['isError'] ?? false);
+            self::assertStringContainsString('did not finish within 2 seconds', $reply['result']['content'][0]['text']);
+            // The stand-in sleeps 30s; the override must cut it far shorter.
+            self::assertLessThan(20.0, $elapsed, 'TYPEPHP_MCP_COMPILE_TIMEOUT was not applied');
+        } finally {
+            if ($previous === false) { putenv('TYPEPHP_MCP_COMPILE_TIMEOUT'); } else { putenv('TYPEPHP_MCP_COMPILE_TIMEOUT=' . $previous); }
+        }
+    }
+
+    public function testSilentCompilerTimesOutInsteadOfSucceeding(): void
+    {
+        // A compiler that stays silent and only then writes used to be
+        // reported as a success after the budget: on Windows the pipe read
+        // ignores the timeout, so runProcess() returned once the child finally
+        // spoke (measured on Windows PHP 8.4 ZTS: a 1 s budget "succeeded" at
+        // 4.2 s). The watchdog plus the post-read deadline check must turn
+        // that into a tool error instead of the late success.
+        $previous = getenv('TYPEPHP_MCP_COMPILE_TIMEOUT');
+        try {
+            putenv('TYPEPHP_MCP_COMPILE_TIMEOUT=1');
+            $started = microtime(true);
+            $reply = $this->withFakeCompiler('silent-then-finish', function (McpServer $server): array {
+                $raw = (string) $server->handleLine((string) json_encode([
+                    'jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/call',
+                    'params' => ['name' => 'check_code', 'arguments' => ['path' => 'examples/hello.php']],
+                ]));
+                return (array) json_decode($raw, true);
+            });
+            $elapsed = microtime(true) - $started;
+            self::assertTrue($reply['result']['isError'] ?? false, 'a silent compiler must not be reported as success');
+            self::assertStringContainsString('did not finish within 1 seconds', $reply['result']['content'][0]['text']);
+            // The stand-in finishes at 4 s; the timeout must return well before.
+            self::assertLessThan(3.5, $elapsed, 'the call waited for the late success instead of timing out');
+        } finally {
+            if ($previous === false) {
+                putenv('TYPEPHP_MCP_COMPILE_TIMEOUT');
+            } else {
+                putenv('TYPEPHP_MCP_COMPILE_TIMEOUT=' . $previous);
+            }
+        }
+    }
+    public function testTimeoutLeavesNoDescendantProcesses(): void
+    {
+        // The stand-in forks a long-lived grandchild and records its pid, then
+        // hangs. After the timeout is reported the grandchild must be gone:
+        // a surviving descendant would keep writing into the build directory
+        // that check() deletes in its finally block.
+        $sandbox = $this->makeSandbox();
+        $spawner = <<<'PHP'
+<?php
+if (in_array('--version', $argv, true)) { echo "TypePHP Compiler (AOT) v9.9.9\n"; exit(0); }
+$child = proc_open('php -r "sleep(300);"', [], $pipes);
+$status = proc_get_status($child);
+file_put_contents(getenv('TYPEPHP_FAKE_PIDFILE'), (string) $status['pid']);
+sleep(300);
+PHP;
+        $this->sandboxWrite($sandbox, 'spawner.php', $spawner);
+        if (stripos(PHP_OS, 'WIN') === 0) {
+            $this->sandboxWrite($sandbox, 'spawner.bat', "@echo off\r\nphp \"%~dp0spawner.php\" %*\r\n");
+            $binary = $sandbox . '/spawner.bat';
+        } else {
+            $this->sandboxWrite($sandbox, 'spawner.sh', "#!/usr/bin/env bash\nexec php \"\$(dirname \"\$0\")/spawner.php\" \"\$@\"\n");
+            @chmod($sandbox . '/spawner.sh', 0755);
+            $binary = $sandbox . '/spawner.sh';
+        }
+        $pidFile = $sandbox . '/child.pid';
+
+        $previousTpc = getenv('TYPEPHP_MCP_TPC');
+        $previousPid = getenv('TYPEPHP_FAKE_PIDFILE');
+        try {
+            putenv('TYPEPHP_MCP_TPC=' . $binary);
+            putenv('TYPEPHP_FAKE_PIDFILE=' . $pidFile);
+            (new ReflectionProperty(CompilerOracle::class, 'compilerPrefix'))->setValue(null, null);
+
+            try {
+                CompilerOracle::runTpc($this->root, ['--dry', 'examples/hello.php'], 2);
+                self::fail('the stand-in should have timed out');
+            } catch (CompilerOracleToolFailure $error) {
+                self::assertStringContainsString('did not finish within 2 seconds', $error->getMessage());
+            }
+
+            $deadline = microtime(true) + 10;
+            while (!is_file($pidFile) && microtime(true) < $deadline) {
+                usleep(50000);
+            }
+            $childPid = (int) trim((string) @file_get_contents($pidFile));
+            self::assertGreaterThan(0, $childPid, 'the stand-in did not record its grandchild pid');
+            self::assertFalse($this->processAlive($childPid), 'a descendant survived the timeout');
+        } finally {
+            if ($previousTpc === false) { putenv('TYPEPHP_MCP_TPC'); } else { putenv('TYPEPHP_MCP_TPC=' . $previousTpc); }
+            if ($previousPid === false) { putenv('TYPEPHP_FAKE_PIDFILE'); } else { putenv('TYPEPHP_FAKE_PIDFILE=' . $previousPid); }
+            (new ReflectionProperty(CompilerOracle::class, 'compilerPrefix'))->setValue(null, null);
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testWatchdogCreationFailureFailsFastAndReapsTheCompiler(): void
+    {
+        // The watchdog is the only thing that can end a silent compiler on
+        // Windows, where a blocked pipe read ignores its timeout. If it cannot
+        // be created, running unprotected means the call returns only when the
+        // child finishes (measured: a 1 s budget "timed out" at 4.2 s). The
+        // call must fail fast and reap the child instead.
+        if (stripos(PHP_OS, 'WIN') !== 0) {
+            self::markTestSkipped('the watchdog only exists on Windows');
+        }
+        $sandbox = $this->makeSandbox();
+        $marker = $sandbox . '/finished.marker';
+        $this->sandboxWrite($sandbox, 'silent.php', <<<'PHP'
+<?php
+usleep(5000000);
+file_put_contents(getenv('TYPEPHP_FAKE_MARKER'), "finished\n");
+PHP);
+        // sys_temp_dir is process-wide, so the unprotected read has to be
+        // provoked in a child process; the child reports its own verdict.
+        $this->sandboxWrite($sandbox, 'probe.php', <<<'PHP'
+<?php
+require getenv('TYPEPHP_SRC') . '/Config.php';
+require getenv('TYPEPHP_SRC') . '/TextUtil.php';
+require getenv('TYPEPHP_SRC') . '/Restrictions.php';
+require getenv('TYPEPHP_SRC') . '/RepoRoot.php';
+require getenv('TYPEPHP_SRC') . '/CompilerOracle.php';
+$method = new ReflectionMethod(CompilerOracle::class, 'runProcess');
+$start = microtime(true);
+try {
+    $method->invoke(null, escapeshellarg(getenv('TYPEPHP_FAKE_PHP')) . ' ' . escapeshellarg(getenv('TYPEPHP_FAKE_STUB')), 1, 8192);
+    fwrite(STDOUT, "returned-without-error\n");
+    exit(1);
+} catch (Throwable $error) {
+    $elapsed = microtime(true) - $start;
+    fwrite(STDOUT, sprintf("elapsed=%.2f msg=%s\n", $elapsed, strtok($error->getMessage(), "\n")));
+    $ok = $elapsed < 3.0 && str_contains($error->getMessage(), 'watchdog could not be created');
+    exit($ok ? 0 : 1);
+}
+PHP);
+        $broken = $sandbox . '/broken-temp-dir-that-does-not-exist';
+        $previousMarker = getenv('TYPEPHP_FAKE_MARKER');
+        $previousSrc = getenv('TYPEPHP_SRC');
+        $previousPhp = getenv('TYPEPHP_FAKE_PHP');
+        $previousStub = getenv('TYPEPHP_FAKE_STUB');
+        try {
+            // The probe reads its inputs from the environment, which exec()
+            // passes on; -d sys_temp_dir then applies to the probe process,
+            // where the watchdog is armed.
+            putenv('TYPEPHP_SRC=' . $this->root->path() . '/tools/typephp-mcp/src');
+            putenv('TYPEPHP_FAKE_PHP=' . PHP_BINARY);
+            putenv('TYPEPHP_FAKE_STUB=' . $sandbox . '/silent.php');
+            putenv('TYPEPHP_FAKE_MARKER=' . $marker);
+            $output = [];
+            $code = 0;
+            @exec(
+                escapeshellarg(PHP_BINARY)
+                . ' -d sys_temp_dir=' . escapeshellarg($broken)
+                . ' ' . escapeshellarg($sandbox . '/probe.php'),
+                $output,
+                $code
+            );
+            $detail = implode("\n", $output);
+            self::assertSame(0, $code, 'unexpected failure: ' . $detail);
+            self::assertStringContainsString('watchdog could not be created', $detail);
+            // The 5 s stand-in would write this marker had it survived. It must
+            // not: the fast-failure path reaps the compiler before reporting.
+            sleep(1);
+            self::assertFileDoesNotExist($marker, 'the compiler survived the watchdog creation failure');
+        } finally {
+            if ($previousMarker === false) { putenv('TYPEPHP_FAKE_MARKER'); } else { putenv('TYPEPHP_FAKE_MARKER=' . $previousMarker); }
+            if ($previousSrc === false) { putenv('TYPEPHP_SRC'); } else { putenv('TYPEPHP_SRC=' . $previousSrc); }
+            if ($previousPhp === false) { putenv('TYPEPHP_FAKE_PHP'); } else { putenv('TYPEPHP_FAKE_PHP=' . $previousPhp); }
+            if ($previousStub === false) { putenv('TYPEPHP_FAKE_STUB'); } else { putenv('TYPEPHP_FAKE_STUB=' . $previousStub); }
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testDisarmWatchdogLeavesNoPingChildBehind(): void
+    {
+        // proc_terminate() only kills the direct cmd.exe on Windows; the ping
+        // child survives for the rest of the armed delay (nearly the compile
+        // timeout, so up to two minutes) and accumulates across calls.
+        if (stripos(PHP_OS, 'WIN') !== 0) {
+            self::markTestSkipped('the watchdog only exists on Windows');
+        }
+        $pingPids = static function (): array {
+            $output = [];
+            @exec('tasklist /FI "IMAGENAME eq PING.EXE" /NH /FO CSV 2>nul', $output);
+            $pids = [];
+            foreach ($output as $line) {
+                $fields = str_getcsv((string) $line);
+                if (count($fields) >= 2 && ctype_digit((string) $fields[1])) {
+                    $pids[] = (int) $fields[1];
+                }
+            }
+            return $pids;
+        };
+        $before = $pingPids();
+        $arm = new ReflectionMethod(CompilerOracle::class, 'armWatchdog');
+        $disarm = new ReflectionMethod(CompilerOracle::class, 'disarmWatchdog');
+
+        $watchdog = $arm->invoke(null, getmypid(), 8);
+        self::assertNotNull($watchdog, 'the watchdog could not be armed');
+        usleep(700000);
+        $armed = array_values(array_diff($pingPids(), $before));
+        self::assertNotSame([], $armed, 'the watchdog did not start a ping child');
+
+        $disarm->invoke(null, $watchdog);
+        usleep(700000);
+        $surviving = array_values(array_intersect($pingPids(), $armed));
+        self::assertSame([], $surviving, 'the ping child survived disarm: ' . implode(',', $surviving));
+    }
+    public function testTimeoutKillsASigtermIgnoringDirectChild(): void
+    {
+        // terminateTree() must SIGKILL the direct child after the grace
+        // period. The descendants-only sweep left a child that ignores
+        // SIGTERM alive: waitForExit() gave up, and the caller's
+        // proc_close() then blocked forever while runProcess() had already
+        // reported "was killed". The stand-in ignores SIGTERM and would
+        // write a completion marker after its own 8 second sleep; with a
+        // 1 second timeout the marker must never appear and the call must
+        // return long before that sleep ends.
+        if (stripos(PHP_OS, 'WIN') === 0 || !function_exists('pcntl_signal')) {
+            self::markTestSkipped('needs POSIX SIGTERM handling (pcntl)');
+        }
+        $sandbox = $this->makeSandbox();
+        $stub = <<<'PHP'
+<?php
+if (in_array('--version', $argv, true)) { echo "TypePHP Compiler (AOT) v9.9.9\n"; exit(0); }
+pcntl_signal(SIGTERM, SIG_IGN);
+sleep(8);
+file_put_contents(getenv('TYPEPHP_FAKE_MARKER'), "finished\n");
+PHP;
+        $this->sandboxWrite($sandbox, 'stub.php', $stub);
+        $this->sandboxWrite($sandbox, 'stub.sh', "#!/usr/bin/env bash\nexec php \"\$(dirname \"\$0\")/stub.php\" \"\$@\"\n");
+        @chmod($sandbox . '/stub.sh', 0755);
+        $marker = $sandbox . '/finished.marker';
+
+        $previousTpc = getenv('TYPEPHP_MCP_TPC');
+        $previousMarker = getenv('TYPEPHP_FAKE_MARKER');
+        try {
+            putenv('TYPEPHP_MCP_TPC=' . $sandbox . '/stub.sh');
+            putenv('TYPEPHP_FAKE_MARKER=' . $marker);
+            (new ReflectionProperty(CompilerOracle::class, 'compilerPrefix'))->setValue(null, null);
+
+            $started = microtime(true);
+            try {
+                CompilerOracle::runTpc($this->root, ['--dry', 'examples/hello.php'], 1);
+                self::fail('the SIGTERM-ignoring stand-in should have timed out');
+            } catch (CompilerOracleToolFailure $error) {
+                self::assertStringContainsString('did not finish within 1 seconds', $error->getMessage());
+            }
+            $elapsed = microtime(true) - $started;
+            // With the fix: about 1.2 s (timeout + grace + kill). Without it
+            // the stand-in survives to the end of its own 8 second sleep.
+            self::assertLessThan(5.0, $elapsed, 'the direct child was not killed after the grace period');
+            self::assertFileDoesNotExist($marker, 'the SIGTERM-ignoring child ran to completion');
+        } finally {
+            if ($previousTpc === false) { putenv('TYPEPHP_MCP_TPC'); } else { putenv('TYPEPHP_MCP_TPC=' . $previousTpc); }
+            if ($previousMarker === false) { putenv('TYPEPHP_FAKE_MARKER'); } else { putenv('TYPEPHP_FAKE_MARKER=' . $previousMarker); }
+            (new ReflectionProperty(CompilerOracle::class, 'compilerPrefix'))->setValue(null, null);
+            $this->removeDir($sandbox);
+        }
+    }
+
+    public function testSymlinkAliasIsNotScannedTwice(): void
+    {
+        // A symlink that aliases a directory inside the same tree used to be
+        // walked again (the visited set was passed by value, so sibling
+        // branches never saw each other's entries). The same file then counted
+        // twice, consuming both the hit limit and the scan budget.
+        $sandbox = $this->makeSandbox();
+        try {
+            $this->sandboxWrite($sandbox, 'src/Test.php', "<?php\nclass AliasProbe {}\n");
+            self::assertTrue(mkdir($sandbox . '/before', 0777, true));
+            $this->sandboxWrite($sandbox, 'before/Marker.php', "<?php\nclass BeforeMarker {}\n");
+
+            $linked = @symlink($sandbox . '/src', $sandbox . '/alias');
+            if ($linked !== true) {
+                self::markTestSkipped('cannot create symlinks in this environment');
+            }
+
+            $code = new CodeIndex($this->root);
+            $text = $code->getSymbol('AliasProbe', [$sandbox]);
+            // Which of the two names is reported depends on scandir() order;
+            // what matters is that the file is reported exactly once.
+            self::assertMatchesRegularExpression('#(src|alias)/Test\.php#', $text);
+            self::assertSame(1, substr_count($text, 'class AliasProbe'), $text);
+            self::assertSame(1, substr_count($text, 'Test.php'), $text);
+        } finally {
+            $this->removeDir($sandbox);
+        }
+    }
+
+    private function processAlive(int $pid): bool
+    {
+        if (stripos(PHP_OS, 'WIN') === 0) {
+            $output = [];
+            $code = 0;
+            @exec('tasklist /FI "PID eq ' . $pid . '" /NH 2>nul', $output, $code);
+            foreach ($output as $line) {
+                if (str_contains((string) $line, (string) $pid)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        $output = [];
+        $code = 0;
+        @exec('kill -0 ' . $pid . ' 2>/dev/null', $output, $code);
+        return $code === 0;
+    }
+
+    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 testResolveInsideRejectsPrefixSiblings(): void
+    {
+        // A sibling directory whose name merely starts with the root's name
+        // must not count as inside it - a symlink in the checkout could
+        // otherwise reach it.
+        $sibling = $this->root->path() . '-evil';
+        self::assertNull($this->root->resolveInside($sibling . '/x.php'));
+        self::assertNull($this->root->resolveInside('../' . basename($sibling) . '/x.php'));
+        // A genuine repo file still resolves.
+        self::assertNotNull($this->root->resolveInside('composer.json'));
+    }
+
+    public function testRepoRootDetectsFromOutsideRepo(): void
+    {
+        // Launching from a directory outside the repository must still locate
+        // the tool resource root: first via TYPEPHP_MCP_ROOT, then via the
+        // source-relative default (this test file lives inside the checkout).
+        $sandbox = $this->makeSandbox();
+        $previousRoot = getenv('TYPEPHP_MCP_ROOT');
+        $previousCwd = getcwd();
+        try {
+            putenv('TYPEPHP_MCP_ROOT=' . $this->root->path());
+            chdir($sandbox);
+            $root = RepoRoot::detect();
+            self::assertSame($this->root->path(), $root->path());
+
+            putenv('TYPEPHP_MCP_ROOT');
+            $root = RepoRoot::detect();
+            self::assertSame($this->root->path(), $root->path());
+        } finally {
+            if ($previousRoot === false) {
+                putenv('TYPEPHP_MCP_ROOT');
+            } else {
+                putenv('TYPEPHP_MCP_ROOT=' . $previousRoot);
+            }
+            chdir((string) $previousCwd);
+            $this->removeDir($sandbox);
+        }
+    }
+
+    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 testProjectRootEnvSplitsPathsPerPlatform(): void
+    {
+        // A Windows path contains a colon, so ':' cannot be a list separator
+        // there: splitting on it turned "D:/work/proj" into "D" and
+        // "/work/proj" and the project was never detected.
+        $sandbox = $this->makeSandbox();
+        $previous = getenv('TYPEPHP_MCP_PROJECT_ROOT');
+        try {
+            $project = $sandbox . '/proj';
+            self::assertTrue(mkdir($project, 0777, true));
+            file_put_contents($project . '/project.yml', "entry: main\n");
+
+            putenv('TYPEPHP_MCP_PROJECT_ROOT=' . $project);
+            $server = new McpServer($this->root);
+            self::assertContains($project, $server->getAutoDirs(), 'single Windows-style path');
+
+            // ';' separates several paths on every platform.
+            $second = $sandbox . '/proj2';
+            self::assertTrue(mkdir($second, 0777, true));
+            file_put_contents($second . '/project.yml', "entry: main\n");
+            putenv('TYPEPHP_MCP_PROJECT_ROOT=' . $project . ';' . $second);
+            $server = new McpServer($this->root);
+            self::assertContains($project, $server->getAutoDirs());
+            self::assertContains($second, $server->getAutoDirs());
+        } finally {
+            if ($previous === false) {
+                putenv('TYPEPHP_MCP_PROJECT_ROOT');
+            } else {
+                putenv('TYPEPHP_MCP_PROJECT_ROOT=' . $previous);
+            }
+            $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'));
+
+        // A percent-encoded drive colon must still strip the leading slash.
+        self::assertSame('d:/git/proj', ProjectDetector::uriToPath('file:///d%3A/git/proj'));
+        // Percent-encoded spaces and non-ASCII survive decoding.
+        self::assertSame('C:/Program Files/x', ProjectDetector::uriToPath('file:///C:/Program%20Files/x'));
+        self::assertSame('D:/中文/项目', ProjectDetector::uriToPath('file:///D:/中文/项目'));
+        // A UNC share stays UNC rather than becoming a relative path.
+        self::assertSame('//server/share/proj', ProjectDetector::uriToPath('file://server/share/proj'));
+    }
+
+    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);
+    }
+}
diff --git a/tools/typephp-mcp/tests/build-lock-test.sh b/tools/typephp-mcp/tests/build-lock-test.sh
new file mode 100644
index 00000000..5717c421
--- /dev/null
+++ b/tools/typephp-mcp/tests/build-lock-test.sh
@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Regression test for build.sh's build lock, clean-then-build order and the
+# single-build contract on CI.
+#
+# Review scenarios:
+#   1. build.sh cleaned build/ BEFORE acquiring the shared user-wide build
+#      lock, so a second invocation that failed to get the lock had already
+#      deleted the sources, objects and cache the first build was still
+#      using. It must refuse to build - keeping build/ intact and never
+#      invoking the compiler - while another build holds the lock.
+#   2. Control: with the lock free it cleans build/ and starts the compiler.
+#   3. On CI (CI=true) the script used to run the compiler BEFORE the clean
+#      and then again after it, so every Unix CI job built twice and threw
+#      the first results away. It must build exactly once, after the clean.
+#
+# Scenario 3 runs on every platform; scenarios 1-2 exercise the shared build
+# lock, which is a Linux-only path.
+#
+# The test runs a sandbox copy of build.sh with fake runtimes (PHP_HOME /
+# PHPX_HOME only need to pass the environment checks) and a php stub that
+# records every invocation. systemd-run is stubbed as well so the whole-tree
+# scope path behaves deterministically on machines without a systemd user
+# session; the stub execs its command unchanged, which is exactly the
+# delegation under test here (the scope must not change how the compiler is
+# reached, only wrap it).
+#
+# Usage: bash tools/typephp-mcp/tests/build-lock-test.sh
+set -uo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+BUILD_SH="$SCRIPT_DIR/../build.sh"
+[[ -f "$BUILD_SH" ]] || { echo "[build-lock-test] FAIL: $BUILD_SH not found" >&2; exit 1; }
+
+work=$(mktemp -d)
+cleanup() { rm -rf "$work"; }
+trap cleanup EXIT
+
+fail() { echo "[build-lock-test] FAIL: $*" >&2; exit 1; }
+
+# Isolate the lock file: build.sh derives it from XDG_RUNTIME_DIR.
+export XDG_RUNTIME_DIR="$work/xdg"
+mkdir -p "$XDG_RUNTIME_DIR"
+lock_file="$XDG_RUNTIME_DIR/codex-build-$(id -u).lock"
+
+# Fake runtimes that pass build.sh's environment checks.
+php_home="$work/php-home"
+phpx_home="$work/phpx-home"
+mkdir -p "$php_home/lib" "$phpx_home/include"
+: > "$php_home/lib/libphp.a"
+printf 'php::empty_string;\n' > "$phpx_home/include/phpx.h"
+
+# Stubs on PATH: php records that the compiler was invoked (and fails, so a
+# sandbox build can never produce a real binary); systemd-run execs its
+# command, standing in for `--scope`.
+mkdir "$work/bin"
+cat > "$work/bin/php" <<PHP
+#!/usr/bin/env bash
+# Records that the compiler was reached. A leftover sentinel means the clean
+# did not run before the build started.
+if [ -f "$work/build/sentinel" ]; then
+    echo "STALE-SENTINEL \$*" >> "$work/php.invocations"
+fi
+echo "\$*" >> "$work/php.invocations"
+exit 97
+PHP
+cat > "$work/bin/systemd-run" <<'STUB'
+#!/usr/bin/env bash
+# Drop the scope options and exec the command: the same contract
+# `systemd-run --user --scope` provides for the build tree.
+args=()
+while [[ $# -gt 0 ]]; do
+    arg=$1
+    shift
+    case "$arg" in
+        --user|--quiet|--collect|--scope) ;;
+        -p|--property) shift ;;
+        --property=*) ;;
+        *) args+=("$arg") ;;
+    esac
+done
+exec "${args[@]}"
+STUB
+chmod +x "$work/bin/php" "$work/bin/systemd-run"
+export PATH="$work/bin:$PATH"
+
+# Sandbox copy of build.sh: its rm -rf build must hit the sandbox, not the
+# checkout.
+cp "$BUILD_SH" "$work/build.sh"
+
+run_build() {
+    # Unset CI so the self-managed path (lock + scope) is exercised.
+    env -u CI -u GITHUB_ACTION PHP_HOME="$php_home" PHPX_HOME="$phpx_home" \
+        bash "$work/build.sh"
+}
+
+# --- 3. CI=true: one build only, and it happens after the clean. -----------
+# Runs on every platform: the CI path needs no lock or memory scope, so it is
+# also the only scenario a non-Linux checkout can verify here.
+mkdir -p "$work/build"
+echo stale > "$work/build/sentinel"
+rm -f "$work/php.invocations"
+
+env CI=true PHP_HOME="$php_home" PHPX_HOME="$phpx_home" \
+    bash "$work/build.sh" > "$work/ci.log" 2>&1
+
+invocations=0
+if [[ -f "$work/php.invocations" ]]; then
+    invocations=$(grep -c . "$work/php.invocations")
+fi
+[[ "$invocations" -eq 1 ]] \
+    || fail "CI ran the compiler $invocations time(s), expected exactly 1 (log: $(tail -n 3 "$work/ci.log" | tr '\n' ' '))"
+grep -q "STALE-SENTINEL" "$work/php.invocations" \
+    && fail "CI invoked the compiler before the clean (sentinel still present)"
+grep -q "project.yml" "$work/php.invocations" \
+    || fail "the CI build never reached the compiler (log: $(tail -n 3 "$work/ci.log" | tr '\n' ' '))"
+[[ ! -f "$work/build/sentinel" ]] || fail "CI did not clean build/ before compiling"
+
+if [[ "$(uname)" != "Linux" ]]; then
+    echo "[build-lock-test] ok (lock scenarios skipped: the shared build lock is a Linux-only path)"
+    exit 0
+fi
+
+# --- 1. Lock held by another build: refuse, keep build/, never compile. ----
+mkdir -p "$work/build"
+echo sentinel > "$work/build/sentinel"
+rm -f "$work/php.invocations"
+
+flock "$lock_file" -c "touch '$work/holder.ready'; while [ ! -f '$work/holder.release' ]; do sleep 0.05; done" &
+holder=$!
+for _ in $(seq 1 100); do
+    [ -f "$work/holder.ready" ] && break
+    sleep 0.05
+done
+[ -f "$work/holder.ready" ] || fail "the lock holder never acquired $lock_file"
+
+run_build > "$work/attempt.log" 2>&1
+attempt_code=$?
+
+touch "$work/holder.release"
+wait "$holder"
+
+[[ $attempt_code -ne 0 ]] || fail "build.sh exited 0 while another build held the lock"
+grep -q "another build holds" "$work/attempt.log" \
+    || fail "build.sh did not fail at the lock step (log: $(tail -n 3 "$work/attempt.log" | tr '\n' ' '))"
+[[ -f "$work/build/sentinel" ]] || fail "build.sh deleted build/ without owning the lock"
+[[ ! -f "$work/php.invocations" ]] || fail "the compiler was invoked although the lock was held: $(cat "$work/php.invocations")"
+
+# --- 2. Control: lock free -> clean runs and the compiler is reached. ------
+echo sentinel2 > "$work/build/sentinel2"
+run_build > "$work/control.log" 2>&1
+
+grep -q "project.yml" "$work/php.invocations" 2>/dev/null \
+    || fail "the control run never reached the compiler (log: $(tail -n 3 "$work/control.log" | tr '\n' ' '))"
+[[ ! -f "$work/build/sentinel2" ]] || fail "the clean step did not run in the control run"
+
+echo "[build-lock-test] ok"
diff --git a/tools/typephp-mcp/tests/mcp-binary-smoke.php b/tools/typephp-mcp/tests/mcp-binary-smoke.php
new file mode 100644
index 00000000..009a9a1f
--- /dev/null
+++ b/tools/typephp-mcp/tests/mcp-binary-smoke.php
@@ -0,0 +1,124 @@
+<?php
+
+/**
+ * Standalone CI driver for the typephp-mcp native binary.
+ *
+ * Builds are useless if the artifact cannot serve a real stdio session, so
+ * every platform CI stage builds the binary first and then runs this script
+ * against it. The script fails (exit 1) when the binary is missing or any
+ * wire check fails - a stage that skips the test when the artifact is absent
+ * would not prove native compatibility.
+ *
+ * Usage:
+ *   php tools/typephp-mcp/tests/mcp-binary-smoke.php [binary] [repoRoot] [cwd]
+ *
+ *   binary     absolute path to typephp_mcp(.exe); defaults to
+ *              TYPEPHP_MCP_BINARY or the platform-default location next to
+ *              this script's parent directory.
+ *   repoRoot   TYPEPHP_MCP_ROOT for the child; defaults to the environment
+ *              or the repository root derived from this script's location.
+ *   cwd        working directory for the child; defaults to repoRoot. Pass a
+ *              temporary directory to prove the server does not depend on
+ *              the dev machine's checkout location.
+ *
+ * --interpreted runs the same checks against the interpreted entry
+ * (run-interpreted.php) so interpreted and AOT results can be compared.
+ */
+
+$options = array_slice($argv, 1);
+$interpreted = in_array('--interpreted', $options, true);
+$options = array_values(array_filter($options, static fn(string $option): bool => $option !== '--interpreted'));
+
+$scriptDir = __DIR__;
+$toolDir = dirname($scriptDir);
+
+$binary = '';
+if (!$interpreted) {
+    if (isset($options[0]) && $options[0] !== '') {
+        $binary = $options[0];
+    } else {
+        $override = getenv('TYPEPHP_MCP_BINARY');
+        if (is_string($override) && $override !== '') {
+            $binary = $override;
+        }
+    }
+}
+
+$repoRoot = $options[$interpreted ? 0 : 1] ?? (getenv('TYPEPHP_MCP_ROOT') ?: dirname($toolDir, 2));
+$repoRoot = str_replace('\\', '/', (string) $repoRoot);
+$cwd = isset($options[$interpreted ? 1 : 2]) && $options[$interpreted ? 1 : 2] !== '' ? $options[$interpreted ? 1 : 2] : null;
+
+require_once $scriptDir . '/McpBinaryDriver.php';
+
+if ($interpreted) {
+    $php = getenv('TYPEPHP_MCP_PHP');
+    if (!is_string($php) || $php === '' || !is_file($php)) {
+        $php = 'php';
+    }
+    $command = [$php, $toolDir . '/run-interpreted.php'];
+    $label = 'interpreted (php run-interpreted.php)';
+} else {
+    if ($binary === '' || !is_file($binary)) {
+        fwrite(STDERR, "[smoke] ERROR: typephp_mcp binary not found (looked at: " . var_export($binary, true) . ").\n"
+            . "[smoke] Build it first: tools/typephp-mcp/build.sh (Unix) or build.bat (Windows).\n");
+        exit(1);
+    }
+    $command = [$binary];
+    $label = basename($binary);
+}
+
+fwrite(STDOUT, "[smoke] target: $label\n[smoke] repoRoot: $repoRoot\n[smoke] cwd: " . ($cwd ?? '(repo root)') . "\n");
+
+$checks = McpBinaryDriver::run($command, $repoRoot, $cwd);
+$failures = 0;
+foreach ($checks as $check) {
+    printf("[smoke] %s %s - %s\n", $check['ok'] ? 'PASS' : 'FAIL', $check['name'], $check['detail']);
+    // Flush per line so a stage that wedges still shows how far it got.
+    fflush(STDOUT);
+    if (!$check['ok']) {
+        $failures++;
+    }
+}
+
+// Deadline probe against a service that stays alive but never replies: the
+// driver must give up at the reply deadline (a normal session proves nothing
+// - every reply there arrives immediately) and, on Windows, the watchdog must
+// have terminated the whole tree. Regression test for the Windows blocked
+// fread() problem: without the watchdog this probe hangs instead of failing.
+fwrite(STDOUT, "[smoke] deadline probe: silent server must not wedge the driver\n");
+fflush(STDOUT);
+$probe = McpBinaryDriver::runSilentServerProbe([PHP_BINARY, '-r', 'while (true) { usleep(50000); }'], 1.0);
+$onWindows = stripos(PHP_OS, 'WIN') === 0;
+$probeOk = !$probe['gotReply']
+    && $probe['elapsed'] < 4.5
+    && (!$onWindows || $probe['treeKilled']);
+printf(
+    "[smoke] %s silent-server reply deadline - elapsed %.2fs, treeKilled: %s\n",
+    $probeOk ? 'PASS' : 'FAIL',
+    $probe['elapsed'],
+    $probe['treeKilled'] ? 'yes' : 'no'
+);
+fflush(STDOUT);
+if (!$probeOk) {
+    $failures++;
+}
+
+fwrite(STDOUT, "[smoke] late-reply probe: data after the deadline must be rejected\n");
+fflush(STDOUT);
+$late = McpBinaryDriver::runSilentServerProbe(
+    [PHP_BINARY, '-r', 'usleep(1600000); echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}\n";'],
+    0.3
+);
+$lateOk = !$late['gotReply'] && $late['elapsed'] < 4.5;
+printf("[smoke] %s late-reply rejection - elapsed %.2fs\n", $lateOk ? 'PASS' : 'FAIL', $late['elapsed']);
+fflush(STDOUT);
+if (!$lateOk) {
+    $failures++;
+}
+
+if ($failures > 0) {
+    fwrite(STDERR, "[smoke] $failures check(s) failed\n");
+    exit(1);
+}
+fwrite(STDOUT, "[smoke] all checks passed\n");
+exit(0);