程式開發代理的 MCP

text mcp：讓程式開發代理透過 Model Context Protocol 導覽、按下按鍵並讀取影格。

text mcp 在處理程序內以無介面模式執行你的 app/ 目錄，並透過 Model Context Protocol 提供服務，讓程式開發代理程式不必使用 DevTools 就能操作。代理程式可以導覽、按鍵、以純文字讀取影格，以及呼叫路由處理常式。

bunx --bun text mcp              # serve ./app over stdiobunx --bun text mcp apps/console # another project

text mcp 需要 Bun。若以 Node 啟動，且 PATH 中有 bun，就會改用 Bun 重新執行，否則會失敗並回報 TX019。MCP 用戶端會替你啟動，因此很少需要手動執行。

設定

每個用戶端都會從你的專案目錄啟動 text mcp。使用 bunx --bun，讓路由檔案以 TypeScript 執行。

OpenCode

opencode.jsonjson

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "textjs": {      "type": "local",      "command": ["bunx", "--bun", "text", "mcp"],      "enabled": true    }  }}

Claude Code

claude mcp add textjs -- bunx --bun text mcp

或將設定提交到版本控制，供團隊使用：

.mcp.jsonjson

{  "mcpServers": {    "textjs": { "command": "bunx", "args": ["--bun", "text", "mcp"] }  }}

Cursor

.cursor/mcp.jsonjson

{  "mcpServers": {    "textjs": { "command": "bunx", "args": ["--bun", "text", "mcp"] }  }}

VS Code

.vscode/mcp.jsonjson

{  "servers": {    "textjs": { "type": "stdio", "command": "bunx", "args": ["--bun", "text", "mcp"] }  }}

若專案位於子目錄，請附加路徑：["--bun", "text", "mcp", "apps/console"]。

工具

工具	說明
`list_routes`	`app/` 中的頁面與路由處理常式，以及目前位置
`navigate`	推入或取代路徑，或執行 `back` / `forward`
`read_frame`	純文字影格，含路由、尺寸、焦點與游標。`styles: true` 會為每個 span 加入顏色與屬性
`press`	按鍵組合：`"down"`、`"ctrl+k"`、`"shift+tab"`、`"tab tab enter"`、`"down*3"`
`type`	逐字元按鍵輸入文字（最多 2000 個字元；更多請用 `paste`）。`submit: true` 會在輸入後按下 Enter
`paste`	單次貼上事件，如 `⌘V`
`scroll`	以滑鼠滾輪捲動 `rows`（及 `cols`）。`<ScrollBox>` 不需取得鍵盤焦點就能用滾輪捲動
`resize`	設定網格的欄數與列數
`inspect_tree`	元件樹及其畫面邊界，以及所有可聚焦的 id
`find`	每個符合項目的邊界，以及其下方的元件
`wait_for`	等待文字出現或消失，或應用程式進入閒置狀態
`logs`	擷取的 `console.*` 輸出與 React 錯誤
`fetch`	在處理程序內呼叫 `route.ts` 處理常式。內文最多讀取 `maxBytes`；事件串流讀取 `streamMs` 後取消
`reload`	編輯檔案後重新匯入應用程式

輸入工具會回傳新的影格，因此代理程式不需要在每次按鍵後另外呼叫 read_frame。目前影格與路由清單也可透過 text://frame 和 text://routes 資源取得。

典型的互動流程：

→ navigate { "path": "/deployments" }→ press { "keys": "down down enter" }← route: /deployments/dpl_6m3ty8  (route /deployments/[id])  title: "Deployment dpl_6m3ty8 · Edge Console"  size: 100×32  frame: 6  idle  focus: _txr_c_ ScrollBox [4,12 92×18]    ▼ Edge Console   Overview   Deployments   Logs   Settings    ← Deployments  /  dpl_6m3ty8   Ready    Production  …

影格與閒置狀態

任何工具讀取影格前，都會等待應用程式進入閒置狀態：沒有排程中的影格、沒有進行中的 fetch，且已連續 50 ms 沒有提交或影格。因此代理程式看到的是輸入後的結果，而非更新到一半的影格。

<Spinner> 或每秒更新一次的圖表，在兩次更新之間仍視為閒置，因此有動畫的頁面也能保持可讀。渲染間隔短於 50 ms 的應用程式永遠不會進入閒置狀態。讀取會在 1.5 秒後停止等待（可用 settleMs 調整），輸出最新影格並標記為 busy。未指定文字的 wait_for 會依自身的 quietMs 等待閒置，若始終未進入閒置狀態，就會回傳錯誤。

座標以從零起算的儲存格表示：x 是欄，y 是列。CJK 字元與 emoji 等寬字元會占用兩欄。

錯誤與記錄

stdout 用於傳輸協定。應用程式的 console.* 輸出、額外的 process.stdout.write 呼叫和 React 錯誤都會改送到 logs，並附上編號，讓代理程式能用 since 只要求新的項目。若上次讀取後有錯誤記錄，下一個影格的標頭會註明。

失敗會以工具錯誤回傳，不會造成當機。逾時的工具會在下一次呼叫執行前取消，因此緩慢的呼叫不會在下一次呼叫的影格中輸入。帶有 Text.js 代碼的錯誤會保留代碼，例如未知按鍵的 TX007。若應用程式載入失敗，每個工具都會說明原因。修正檔案後呼叫 reload。

選項

選項	說明
`--path <pathname>`	初始路由（預設為 `/`）
`--cols` / `--rows`	網格大小（預設使用 `text.config.ts` 中的 `viewport`，未設定時為 100×32）
`--theme <name>`	主題預設集
`--no-config`	忽略 `text.config.ts`
`--verbose`	同時將擷取的記錄寫入 stderr

運作方式

text mcp 以與 text run 相同的方式執行應用程式：預先匯入所有路由模組，App Router 使用記憶體中的歷史記錄，同源的 fetch("/api/…") 呼叫則在處理程序內執行處理常式。影格會送到離屏的儲存格網格，而非終端機。伺服器端渲染的頁面（export const runtime = "server"）及其 async function 元件會如同在 text dev 中一樣，於處理程序內渲染，並在完成後讀取影格。

reload 會卸載應用程式，從 Bun 的模組快取中清除所有專案模組（包括 app/ 之外的檔案），再次掃描 app/，並在目前位置重新掛載。

若要將伺服器嵌入自己的處理程序，或使用其他傳輸方式：

import { createTextMcpServer } from "@textjs/app/mcp";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";const { server, controller } = createTextMcpServer({ root: process.cwd() });await server.connect(new StdioServerTransport());void controller.start();

限制

應用程式在 Bun 中執行，不在瀏覽器中執行。window 和 document 如同在 text run 中一樣未定義。
每個伺服器執行一個應用程式，使用一個網格。每個 MCP 用戶端都會啟動自己的伺服器。
text mcp 會執行自己的無介面應用程式副本。無法連接到以 text dev 開啟的瀏覽器分頁。

#設定

#OpenCode

#Claude Code

#Cursor

#VS Code

#工具

#影格與閒置狀態

#錯誤與記錄

#選項

#運作方式

#限制

設定