⁦MCP⁩ برای عامل‌های کدنویسی

دستور text mcp دایرکتوری app/ شما را بدون رابط گرافیکی و درون همان پردازش اجرا می‌کند و آن را از طریق پروتکل زمینهٔ مدل ارائه می‌دهد تا عامل‌های کدنویسی بتوانند بدون DevTools از آن استفاده کنند. عامل پیمایش می‌کند، کلیدها را فشار می‌دهد، فریم‌ها را به‌صورت متن ساده می‌خواند و کنترل‌گرهای مسیر را فراخوانی می‌کند.

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

دستور text mcp به Bun نیاز دارد. اگر با Node شروع شود، وقتی bun در PATH شما باشد، خود را با Bun دوباره اجرا می‌کند و در غیر این صورت با خطای TX019 متوقف می‌شود. کلاینت‌های MCP آن را برای شما شروع می‌کنند، بنابراین به‌ندرت آن را دستی اجرا می‌کنید.

#راه‌اندازی

هر کلاینت دستور text mcp را از دایرکتوری پروژهٔ شما شروع می‌کند. از دستور bunx --bun استفاده کنید تا فایل‌های مسیر به‌صورت TypeScript اجرا شوند.

#OpenCode

{  "$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

یا آن را برای تیم کامیت کنید:

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

#Cursor

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

#VS Code

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

برای پروژه‌ای در یک زیردایرکتوری، مسیر را به انتها اضافه کنید: ["--bun", "text", "mcp", "apps/console"].

#ابزارها

ابزارهای ورودی فریم جدید را برمی‌گردانند، بنابراین عامل پس از هر کلید به فراخوانی جداگانهٔ 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 و ایموجی دو ستون اشغال می‌کنند.

#خطاها و گزارش‌ها

⁦stdout⁩ پروتکل را منتقل می‌کند. خروجی console.* برنامهٔ شما، فراخوانی‌های پراکندهٔ process.stdout.write و خطاهای React به‌جای آن به logs می‌روند و شماره‌گذاری می‌شوند تا عامل بتواند با since فقط ورودی‌های جدید را درخواست کند. اگر از آخرین خواندن خطاهایی ثبت شده باشند، سربرگ فریم بعدی این موضوع را نشان می‌دهد.

شکست‌ها به‌صورت خطای ابزار برمی‌گردند و هرگز به ازکارافتادن منجر نمی‌شوند. ابزاری که مهلتش تمام شود پیش از اجرای فراخوانی بعدی لغو می‌شود، بنابراین یک فراخوانی کند هرگز در فریم فراخوانی بعدی تایپ نمی‌کند. خطاهای دارای کد Text.js آن را حفظ می‌کنند، برای مثال TX007 برای کلیدی ناشناخته. اگر برنامه بارگیری نشود، هر ابزار دلیل آن را توضیح می‌دهد. فایل را اصلاح کنید و ابزار reload را فراخوانی کنید.

#گزینه‌ها

#نحوهٔ کار

دستور 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 اجرا می‌شود، نه در مرورگر. مانند text run، مقادیر window و document تعریف‌نشده هستند.
• هر سرور یک برنامه با یک شبکه اجرا می‌کند. هر کلاینت MCP سرور خودش را شروع می‌کند.
• دستور text mcp نسخهٔ بدون رابط گرافیکی خودش از برنامه را اجرا می‌کند. نمی‌تواند به زبانهٔ مرورگری که با text dev باز شده است متصل شود.