Locus MCP ناوبری معنایی را جایگزین جست‌وجوی متنی در عامل‌های کدنویس کرد

اگر امروز از عامل‌های کدنویس برای مدیریت پروژه‌های بزرگ استفاده می‌کنید، احتمالاً با توهمات آن‌ها در شناسایی توابع مشابه یا گم‌شدن در میان فایل‌های متعدد دست‌وپنجه نرم کرده‌اید. این مشکل ریشه در تکیهٔ بیش از حد این مدل‌ها به جست‌وجوی متنی دارد، در حالی که کدنویسی واقعی نیازمند درک ساختاری است. عامل‌های کدنویسی اغلب در درک یک کدبیس دچار مشکل می‌شوند و مکرراً رشته‌های متنی مشابه را با هم اشتباه می‌گیرند یا تعاریف فعال (Active Definitions) را نادیده می‌گیرند.

طبق یک راهنمای فنی که در ۴ اوت ۲۰۲۶ منتشر شد، ابزار Locus MCP با ایجاد پلی میان میزبان‌های عامل و سرورهای پروتکل سرور زبان (Language Server Protocol یا LSP) این شکاف را پر می‌کند. یک عامل ممکن است یک فایل را سریعاً ویرایش کند اما همچنان کدبیس را به اشتباه بفهمد؛ جست‌وجوی متنی رشته‌های منطبق را پیدا می‌کند، اما نمی‌تواند با اطمینان بگوید کدام تعریف فعال است، کدام فراخوان‌ها (Callers) تحت تأثیر قرار می‌گیرند یا یک مقدار از چه نوعی (Type) است.

اکثر عامل‌ها برای پیمایش کد به جست‌وجوی متنی متکی هستند. در حالی که ابزاری مانند grep رشته‌های منطبق را می‌یابد، اما نمی‌تواند بین یک تعریف تابع، یک کامنت یا یک مورد تست (Test Case) تمایز قائل شود. برای مثال، اگر یک عامل بخواهد نام parseConfig را تغییر دهد، grep می‌تواند هر occurrence از این متن را لیست کند، از جمله رشته‌ها، تست‌ها، فایل‌های تولید شده و نمادهای غیرمرتبط. این فقدان آگاهی معنایی (Semantic Awareness) منجر به بروز خطا در هنگام ریفکتورینگ و درک کلی نادرست از ساختار پروژه می‌شود.

همان‌طور که در تحلیل‌های پیشین ما درباره‌ی پروتکل زمینهٔ مدل (MCP) اشاره کردیم، هدف این است که مدل‌ها به ابزارهای خارجی دسترسی دقیق‌تری داشته باشند. این رویکرد در راستای تلاش‌های گسترده‌تری است که در آن استانداردهای MCP برای دسترسی امن عامل‌ها به کدبیس تعریف شده‌اند تا تعاملات مدل با فایل‌ها ساختاریافته‌تر شود. Locus MCP دقیقاً همین کار را می‌کند؛ این ابزار لایه‌ای سبک است که فراخوانی‌های ابزاری MCP را به درخواست‌های LSP ترجمه می‌کند. به جای حدس زدن بر اساس الگوهای متنی، عامل اکنون می‌تواند مستقیماً از سرور زبان بپرسد که یک شناسه دقیقاً به کدام تعریف اشاره دارد و کدام مکان‌های منبع (Source Locations) به آن تعریف خاص ارجاع می‌دهند. Locus یک لایه MCP کوچک بین میزبان عامل و آن سرورهای زبان است و به عامل اجازه می‌دهد از همان سرویس‌های معنایی عمومی استفاده کند که IDEها ارائه می‌دهند.

به نقل از مستندات dev.to، این ابزار شش قابلیت کلیدی را در اختیار عامل قرار می‌دهد:

• locate: یافتن یک نماد خاص یا لیست تمام نمادهای موجود در یک فایل.
• refs: شناسایی تمام ارجاعات یا پیاده‌سازی‌های یک نماد.
• hover: بازگرداندن اطلاعات دقیق دربارهٔ نوع داده (Type) و مستندات مرتبط با آن.
• diagnostics: گزارش خطاهای فعال و هشدارهای موجود در کد.
• status: تأیید آماده بودن و در دسترس بودن سرور زبان.
• rename: پیش‌نمایش تأثیر عملیات تغییر نام بدون اعمال واقعی ویرایش روی فایل.

برای پیاده‌سازی این جریان کاری، کاربر به Node.js نسخه ۲۲ یا بالاتر و یک میزبان سازگار با MCP مانند Cursor، Codex یا Claude Code نیاز دارد. همچنین باید سرور زبان مربوط به هر زبان برنامه‌نویسی هدف نصب شود:

• TypeScript/JavaScript: نصب از طریق دستور npm install -g typescript-language-server typescript.
• Python: گزینه مستند شده استفاده از pip install pyright است.
• Go: استفاده از gopls.
• Rust: استفاده از rust-analyzer.

فرآیند نصب با اجرای دستور npx @paladini/locus-mcp init در ریشه پروژه آغاز می‌شود تا فایل‌های پیکربندی locus.toml و locus.json ایجاد شوند. سپس دستور npx @paladini/locus-mcp check بررسی می‌کند که آیا باینری‌های لازم در مسیر سیستم (PATH) موجود هستند یا خیر. یک بررسی موفقیت‌آمیز برای TypeScript باید typescript-language-server را شناسایی کند؛ اگر باینری گم شده باشد، این یک مشکل در نصب است و نه مشکلی در MCP.

در پروژه‌های چندزبانه، کاربران باید تنها سرورهای مورد نیاز را نصب کرده و زبان‌های «گرم» (Warm Languages) را در فایل locus.toml با فرمت زیر پیکربندی کنند:

root = "."
warm = ["typescript", "python"]

Locus هنگام پیمایش به سمت بالای دایرکتوری فعلی، اولویت خاصی برای فایل‌ها دارد: ابتدا به دنبال locus.toml می‌گردد، سپس locus.json و در نهایت .lsp.json. در حالی که locus.toml برای تعیین ریشه و زبان‌های گرم راحت است، locus.json می‌تواند دستورات خاص، آرگومان‌ها، شناسه‌های زبان (Language IDs) و پسوندهای فایل را توصیف کند. زمانی که هیچ آرایه‌ای از سرورهای سفارشی ارائه نشود، Locus از پیش‌فرض‌های داخلی برای TypeScript، Python، Go و Rust استفاده می‌کند.

یکپارچگی با میزبان‌ها متفاوت است. میزبان، سرور را بر اساس نیاز (On Demand) استارت می‌زند، بنابراین کاربران معمولاً دستور serve را به صورت دستی در ترمینال اجرا نمی‌کنند.

برای Cursor، کاربران باید فایل .cursor/mcp.json را در پروژه ایجاد کنند:

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

برای Codex، ورودی معادل در سطح پروژه به صورت TOML است:

[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp", "serve"]
cwd = "/absolute/path/to/your/project"

مسیر مطلق پروژه (cwd) بسیار حیاتی است. این مسیر به Locus می‌گوید دقیقاً کدام کدبیس و پیکربندی را باید بازرسی کند. پس از ذخیره، کاربران باید سرورهای MCP را مجدداً بارگذاری کرده یا میزبان را ری‌استارت کنند.

برای تأیید صحت اتصال، یک گردش‌کار سه مرحله‌ای پیشنهاد می‌شود. ابتدا از عامل بخواهید ابزار status را فراخوانی کند: «ابزار status در Locus MCP را فراخوانی کن و به من بگو کدام سرور زبان آماده هستند.» یک پاسخ readiness تأیید می‌کند که میزبان می‌تواند Locus را استارت بزند. اگر پاسخ server_starting بود، کمی صبر کنید؛ اگر server_unavailable بود، دوباره دستور check را اجرا کنید.

در مرحله دوم، یک جست‌وجوی معنایی را در پروژه‌ای با یک نماد شناخته شده امتحان کنید: «از Locus locate استفاده کن تا پیدا کنی UserService.authenticate کجا تعریف شده است. از grep استفاده نکن.» این کار ثابت می‌کند که تفکیک معنایی (Semantic Resolution) در حال کار است.

در نهایت، یک تست بازبینی ریفکتور شامل یک درخواست دو مرحله‌ای است: «قبل از تغییر parseConfig، از Locus استفاده کن تا تعریف آن را بیابد و تمام ارجاعاتش را لیست کند. قبل از ویرایش هر چیزی، فایل‌ها و خطوط را به من نشان بده.» کاربران همچنین می‌توانند با درخواست از عامل برای اجرای Locus diagnostics روی یک فایل خاص (مانند src/api/handler.ts)، خطاها و هشدارها را گزارش گیرند.

از نظر معماری، Locus خودش تجزیه‌گر (Parser) ندارد، بلکه سرورهای زبان را به عنوان فرآیندهای فرزند (Child Processes) اجرا می‌کند و فراخوانی‌های ابزاری MCP را به درخواست‌های سرور زبان ترجمه می‌کند. این معماری به این معناست که نتایج به سرور زبان، پیکربندی پروژه، وضعیت ایندکس‌گذاری و فایل‌های قابل مشاهده از ریشه انتخاب شده بستگی دارد. یک تیک سبز در هنگام نصب به معنای وجود فایل اجرایی در PATH است، اما تضمین نمی‌کند که هر Workspace بلافاصله پاسخ مفیدی تولید کند.

از نظر امنیتی، یک ملاحظه اساسی وجود دارد. چون Locus سرورهای زبان را به عنوان فرآیندهای فرزند اجرا می‌کند و دستورات پیکربندی شده را اسپاون می‌کند، سیاست امنیتی صراحتاً هشدار می‌دهد که پیکربندی‌ها باید قبل از استفاده بازبینی شوند. کاربران باید پیش از اعتماد به یک پروژه، فایل‌های locus.json و .lsp.json را بررسی کنند.

Locus کد را ویرایش نمی‌کند، حافظه عامل را ذخیره نمی‌کند و جایگزین grep نمی‌شود. ابزار rename تنها یک پیش‌نمایش است و عامل همچنان باید تغییر واقعی را اعمال کند. برای ویرایش نمادین یا حافظه پایدار، مستندات به جایگزین‌هایی مانند Serena اشاره می‌کنند.

این تغییر رویکرد، عامل‌های هوش مصنوعی را از «ویرایشگرهای متن» به «ناوبرهای معنایی» تبدیل می‌کند. با جداسازی جست‌وجوی متنی ساده (grep) از تحلیل ساختاری (LSP)، نرخ توهم (Hallucination) — یعنی وقتی مدل با اطمینان چیزی می‌گوید که وجود ندارد — در ریفکتورهای پیچیده کاهش می‌یابد. تغییر مفید در اینجا افزودن یک دستور جست‌وجوی دیگر نیست، بلکه ایجاد یک مرز آگاهانه بین جست‌وجوی متنی و پیمایش معنایی کد برای عامل است.

برای توسعه‌دهنده، این به معنای صرف زمان کمتر برای اصلاح عاملی است که یک متغیر را در یک کامنت تغییر داده اما آن را در منطق کد فراموش کرده است. این امر معیار کیفیت عامل را از «چقدر خوب می‌تواند جست‌وجو کند» به «چقدر خوب می‌تواند در گراف وابستگی‌ها پیمایش کند» تغییر می‌دهد.

در حالی که Locus جایگزین نیاز به grep نمی‌شود — که برای لاگ‌ها، کامنت‌ها و کلیدهای پیکربندی مفید باقی می‌ماند — اما گاردریل‌های لازم برای ویرایش نمادین را فراهم می‌کند. تکیه بر سرورهای زبان خارجی به این معنی است که هوشمندی عامل اکنون به کیفیت پیکربندی LSP پروژه گره خورده است.

برای شروع بهبود دقت عامل، سعی کنید Locus را در پروژه بعدی TypeScript یا Python خود ادغام کنید و نتایج یک فراخوانی refs را با یک جست‌وجوی استاندارد grep مقایسه کنید. اولین وظیفه پیمایش کدی که به یک سرور MCP می‌سپارید چه خواهد بود: یافتن تعاریف، بازبینی ارجاعات قبل از ریفکتور، یا بررسی تشخیص‌ها (Diagnostics) بعد از یک ویرایش؟

گام بعدی شما

• اگر از Cursor یا Claude Code استفاده می‌کنید، Locus MCP را روی یک پروژه TypeScript یا Python نصب کنید.
• نتایج یک فراخوانی refs را با جست‌وجوی معمولی grep مقایسه کنید تا تفاوت دقت را ببینید.
• از عامل بخواهید پیش از هر تغییر گسترده در نام توابع، ابتدا لیست تمام ارجاعات را با ابزار Locus استخراج کند.

اما این تنها بخشی از تکامل ابزارهای کدنویسی است؛ برای درک اینکه چگونه حافظه بلندمدت می‌تواند دقت این عامل‌ها را بیشتر کند، تحلیل ما درباره‌ی Serena را بخوانید.