zames_pro 2.12.0 → 2.13.0

package/README.md

@@ -106,6 +106,42 @@ Skills and custom commands show up in the «/» completion list and in `/help`.
 /init [--force]               analyze the project and create AGENTS.md
 ```
 
+## MCP (external tools)
+
+zames can use tools from [MCP](https://modelcontextprotocol.io) servers.
+The flagship example is @playwright/mcp: it gives the agent a real browser
+(navigate, click, snapshot, type, ...) on top of the one zames already uses
+for the DeepSeek chat.
+
+Drop a config file (same shape as Claude Code / Cursor):
+
+- `~/.zames/mcp.json` - global
+- `<project>/.zames/mcp.json` - project-scoped (later files win)
+- `<project>/.mcp.json` - the common MCP name
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--headless", "--isolated"]
+    }
+  }
+}
+```
+
+IMPORTANT: keep the MCP browser isolated. @playwright/mcp defaults to the
+SAME profile directory as zames (~/.zames/profile). If it is launched
+without --isolated (or without its own --user-data-dir), the MCP browser
+and the agent browser fight over one profile and the DeepSeek chat shows
+"Something went wrong when opening your profile". Always pass --isolated
+as in the example above.
+Servers can also be remote ("url": "https://...", "transport": "sse").
+Their tools show up in the agent as `server__tool` (e.g.
+`playwright__browser_navigate`) and are listed with `/mcp` and in `/status`.
+A server that fails to connect is skipped with a warning and never breaks the
+agent.
+
 ## Configuration
 
 Global config: `~/.zames/config.json`

package/dist/i18n.js

@@ -246,6 +246,16 @@ const CATALOG = {
     'cd.failed': { ru: 'Не удалось перейти: {v}', en: 'Failed to change directory: {v}' },
     'calibrate': { ru: '\n🔧 Режим калибровки селекторов\n', en: '\n🔧 Selector calibration mode\n' },
     'reload.auto_partial': { ru: '⚠ авто-reload: часть модулей не загрузилась, работаю на прежней версии:', en: '⚠ auto-reload: some modules failed, using previous version:' },
+    // ---------- MCP ----------
+    'help.cmd.mcp': { ru: '/mcp                     показать MCP-серверы и их инструменты', en: '/mcp                     show MCP servers and their tools' },
+    'mcp.loaded': { ru: 'MCP: подключено инструментов {n} ({servers})', en: 'MCP: {n} tool(s) from {servers}' },
+    'mcp.server_error': { ru: 'MCP-сервер {name} недоступен: {error}', en: 'MCP server {name} unavailable: {error}' },
+    'mcp.load_failed': { ru: 'Не удалось загрузить MCP: {v}', en: 'Failed to load MCP: {v}' },
+    'mcp.none': { ru: 'MCP-серверы не настроены.', en: 'No MCP servers configured.' },
+    'mcp.hint': { ru: 'Добавь ~/.zames/mcp.json или <project>/.zames/mcp.json.', en: 'Add ~/.zames/mcp.json or <project>/.zames/mcp.json.' },
+    'mcp.title': { ru: 'MCP-серверы (инструментов: {n}):', en: 'MCP servers ({n} tools):' },
+    'mcp.status_error': { ru: '(ошибка: {v})', en: '(error: {v})' },
+    'status.mcp': { ru: 'MCP-инструменты: {v}', en: 'MCP tools: {v}' },
     // ---------- config menu ----------
     'cfg.group.ui': { ru: 'Интерфейс', en: 'Interface' },
     'cfg.group.agent': { ru: 'Агент', en: 'Agent' },

package/dist/index.js

@@ -91,6 +91,7 @@ function loadLastChat(workdir = '') {
 // so we pick the extension ourselves — from the actual file of the current module.
 const SRC_EXT = /[.]ts$/.test(new URL(import.meta.url).pathname) ? '.ts' : '.js';
 const RELOADABLE = [
+    'mcp',
     'tools',
     'agent-loop',
     'system-prompt',
@@ -114,6 +115,7 @@ const mod = {
     selfList,
     closeWeb,
     createSpinner,
+    createMcpPool: null,
 };
 async function reloadModules() {
     const stamp = Date.now();
@@ -150,6 +152,8 @@ async function reloadModules() {
         mod.closeWeb = pick('web', 'closeWeb');
     if (pick('spinner', 'createSpinner'))
         mod.createSpinner = pick('spinner', 'createSpinner');
+    if (pick('mcp', 'createMcpPool'))
+        mod.createMcpPool = pick('mcp', 'createMcpPool');
     return { count: loaded.size, errors };
 }
 // Initial load so that mod.buildSystemPrompt and the rest are populated.
@@ -265,6 +269,7 @@ const SLASH_COMMANDS = [
     { name: '/skills', key: 'help.cmd.skills' },
     { name: '/memory', key: 'help.cmd.memory' },
     { name: '/init', key: 'help.cmd.init' },
+    { name: '/mcp', key: 'help.cmd.mcp' },
     { name: '/debug-dom', key: 'help.cmd.debug_dom' },
     { name: '/self-review', key: 'help.self.review' },
     { name: '/self-fix', key: 'help.self.fix' },
@@ -901,6 +906,23 @@ async function main() {
         console.log(theme.system(t('msg.transcript', { v: transcript.file })));
     }
     const undo = new UndoStore(config.undo);
+    // MCP servers: optional external tool providers (e.g. @playwright/mcp).
+    let mcpPool = null;
+    try {
+        mcpPool = await mod.createMcpPool({ workdir: currentWorkdir });
+        const st = mcpPool.status();
+        if (st.toolCount > 0) {
+            const names = st.servers.filter((x) => !x.error).map((x) => x.name).join(', ');
+            console.log(theme.system(t('mcp.loaded', { n: String(st.toolCount), servers: names })));
+        }
+        for (const srv of st.servers) {
+            if (srv.error)
+                console.error(theme.warn(t('mcp.server_error', { name: srv.name, error: srv.error })));
+        }
+    }
+    catch (e) {
+        console.error(theme.warn(t('mcp.load_failed', { v: e.message })));
+    }
     const browser = new DeepSeekBrowser({
         headless,
         debug,
@@ -926,6 +948,8 @@ async function main() {
     // One-shot mode
     if (task) {
         const tools = mod.createTools(currentWorkdir, { undo });
+        if (mcpPool)
+            tools.push(...mcpPool.tools);
         let freshChat = true;
         let sendSystemPrompt = true;
         // By default we start a new chat. To continue a previous session —
@@ -962,6 +986,8 @@ async function main() {
         });
         await browser.close();
         await mod.closeWeb().catch(() => { });
+        if (mcpPool)
+            await mcpPool.close().catch(() => { });
         transcript.close();
         return;
     }
@@ -990,6 +1016,8 @@ async function main() {
         // Close the lazy headless browser from web.js, otherwise it would stay
         // as a separate process after the agent exits.
         await mod.closeWeb().catch(() => { });
+        if (mcpPool)
+            await mcpPool.close().catch(() => { });
         transcript.close();
         console.log(theme.system(String.fromCharCode(10) + t('msg.bye')));
         process.exit(0);
@@ -1752,6 +1780,24 @@ async function main() {
             console.log(theme.system(currentWorkdir));
             continue;
         }
+        if (lower === '/mcp') {
+            if (!mcpPool) {
+                console.log(theme.dim(t('mcp.none')));
+                console.log(theme.dim(t('mcp.hint')));
+                continue;
+            }
+            const st = mcpPool.status();
+            console.log(theme.system(t('mcp.title', { n: String(st.toolCount) })));
+            for (const srv of st.servers) {
+                if (srv.error) {
+                    console.log('  ' + theme.user(srv.name) + ' ' + theme.dim(t('mcp.status_error', { v: srv.error })));
+                }
+                else {
+                    console.log('  ' + theme.user(srv.name) + ' ' + theme.dim('(' + String(srv.tools.length) + ')'));
+                }
+            }
+            continue;
+        }
         if (lower === '/skills') {
             const { loadSkills } = await import('./context.js');
             const skills = await loadSkills(currentWorkdir);
@@ -1926,6 +1972,9 @@ async function main() {
                 v: transcript.file || t('common.off'),
             })));
             console.log(theme.system(t('status.locale', { v: localeDisplayName(currentLocale) })));
+            console.log(theme.system(t('status.mcp', {
+                v: mcpPool ? String(mcpPool.status().toolCount) : t('common.none'),
+            })));
             continue;
         }
         if (lower === '/config' || lower.startsWith('/config ')) {
@@ -2032,6 +2081,8 @@ async function main() {
         await autoReload();
         transcript.log('user_task', { task: taskText, workdir: currentWorkdir });
         const tools = mod.createTools(currentWorkdir, { undo });
+        if (mcpPool)
+            tools.push(...mcpPool.tools);
         if (editor)
             editor.busy = true;
         try {
@@ -2067,6 +2118,8 @@ async function main() {
         editor.dispose();
     await browser.close().catch(() => { });
     await mod.closeWeb().catch(() => { });
+    if (mcpPool)
+        await mcpPool.close().catch(() => { });
     transcript.close();
 }
 main().catch((e) => {

package/dist/mcp.js

@@ -0,0 +1,327 @@
+/** Names of the servers found in a config, before any connection. */
+export async function listConfiguredServers(workdir) {
+    const files = await discoverConfigFiles(workdir);
+    const config = await loadConfigFiles(files);
+    const servers = config.mcpServers || {};
+    return Object.keys(servers).filter((n) => !servers[n].disabled);
+}
+// @playwright/mcp defaults its --user-data-dir to the SAME profile zames uses
+// (~/.zames/profile). Two chromium instances on one profile break each other:
+// the chat page shows "Something went wrong when opening your profile" and
+// the session is lost. So when a stdio server looks like @playwright/mcp we
+// auto-add --isolated (in-memory profile) unless the user already chose a
+// profile (--isolated / --user-data-dir / --extension / --cdp-endpoint).
+export function hardenPlaywrightArgs(command, args) {
+    const hay = (String(command || '') + ' ' + args.join(' ')).toLowerCase();
+    if (!hay.includes('playwright') || !hay.includes('mcp'))
+        return args;
+    if (args.some((a) => a === '--isolated' || a.startsWith('--user-data-dir') || a === '--extension' || a.startsWith('--cdp-endpoint'))) {
+        return args;
+    }
+    return [...args, '--isolated'];
+}
+/** Parse one config object into a validated map (best-effort). */
+export function normalizeServerConfig(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const out = {};
+    if (typeof r.command === 'string')
+        out.command = r.command;
+    if (Array.isArray(r.args))
+        out.args = r.args.map((a) => String(a));
+    if (r.env && typeof r.env === 'object') {
+        out.env = {};
+        for (const [k, v] of Object.entries(r.env)) {
+            out.env[k] = String(v);
+        }
+    }
+    if (typeof r.cwd === 'string')
+        out.cwd = r.cwd;
+    if (typeof r.url === 'string')
+        out.url = r.url;
+    if (r.transport === 'sse' || r.transport === 'streamable-http') {
+        out.transport = r.transport;
+    }
+    if (r.headers && typeof r.headers === 'object') {
+        out.headers = {};
+        for (const [k, v] of Object.entries(r.headers)) {
+            out.headers[k] = String(v);
+        }
+    }
+    if (r.disabled === true)
+        out.disabled = true;
+    if (!out.command && !out.url)
+        return null;
+    return out;
+}
+/** Candidate config paths, ordered from global to project-local. */
+export async function discoverConfigFiles(workdir) {
+    const path = await import('path');
+    const os = await import('os');
+    const fsMod = await import('fs/promises');
+    const candidates = [
+        path.join(os.homedir(), '.zames', 'mcp.json'),
+        path.join(workdir, '.zames', 'mcp.json'),
+        path.join(workdir, '.mcp.json'),
+    ];
+    const out = [];
+    for (const c of candidates) {
+        if (await fsMod.stat(c).catch(() => null))
+            out.push(c);
+    }
+    return out;
+}
+/** Read and merge every config file. Later files override earlier ones. */
+export async function loadConfigFiles(files) {
+    const merged = {};
+    const fsMod = await import('fs/promises');
+    for (const f of files) {
+        try {
+            const raw = await fsMod.readFile(f, 'utf-8');
+            const json = JSON.parse(raw);
+            const servers = json.mcpServers;
+            if (!servers || typeof servers !== 'object')
+                continue;
+            for (const [name, cfg] of Object.entries(servers)) {
+                const normalized = normalizeServerConfig(cfg);
+                if (normalized)
+                    merged[name] = normalized;
+            }
+        }
+        catch {
+            // Best-effort: a broken MCP config must not break the agent.
+        }
+    }
+    return { mcpServers: merged };
+}
+/* ---------- json-schema -> agent parameters ---------- */
+// MCP tools describe their arguments with a JSON Schema. zames own ToolDef
+// uses a flat map (name -> 'type?'), which is what the system-prompt shows
+// to the model. We convert the schema into that flat form so MCP tools look
+// like built-in ones and the model already knows the convention.
+//
+// We also keep the full schema in the tool description, so the model sees
+// descriptions/enums/required fields that the flat map cannot convey.
+export function jsonSchemaToParams(schema) {
+    const out = {};
+    if (!schema || typeof schema !== 'object')
+        return out;
+    const s = schema;
+    if (!s.properties || typeof s.properties !== 'object')
+        return out;
+    const required = new Set(Array.isArray(s.required) ? s.required : []);
+    for (const [key, raw] of Object.entries(s.properties)) {
+        const prop = (raw || {});
+        let type = typeof prop.type === 'string' ? prop.type : '';
+        if (Array.isArray(prop.type) || prop.enum)
+            type = 'value';
+        if (!type)
+            type = 'value';
+        out[key] = type + (required.has(key) ? '' : '?');
+    }
+    return out;
+}
+// Append the raw JSON Schema to the description so the model sees field
+// descriptions and enums. The flat map alone cannot convey them, and MCP
+// tools (browser_snapshot, browser_click, ...) rely on them heavily.
+export function describeParamsExternally(description, schema) {
+    const type = schema?.type;
+    if (!schema || type !== 'object')
+        return description;
+    try {
+        const json = JSON.stringify(schema);
+        if (json.length > 4000)
+            return description;
+        return description + '\nJSON Schema: ' + json;
+    }
+    catch {
+        return description;
+    }
+}
+/* ---------- result rendering ---------- */
+// MCP tool results are a list of content blocks (text, image, resource, ...)
+// and an isError flag. The agent needs a single string for the tool result
+// message. Images are summarized (the model cannot see them through
+// DeepSeek web anyway), text is joined.
+export function renderMcpResult(result) {
+    const r = (result || {});
+    if (r.toolResult !== undefined && !r.content) {
+        return formatResultString(r.toolResult, r.isError);
+    }
+    const parts = [];
+    for (const block of r.content || []) {
+        if (!block || typeof block !== 'object') {
+            parts.push(String(block ?? ''));
+            continue;
+        }
+        const b = block;
+        const type = String(b.type ?? '');
+        if (type === 'text') {
+            parts.push(String(b.text ?? ''));
+        }
+        else if (type === 'image') {
+            parts.push('[image ' + String(b.mimeType ?? 'unknown') + ', written to disk by the MCP server]');
+        }
+        else if (type === 'resource') {
+            const res = (b.resource || {});
+            if (typeof res.text === 'string') {
+                parts.push(String(res.uri ?? '') + String.fromCharCode(10) + res.text);
+            }
+            else if (typeof res.blob === 'string') {
+                parts.push('[binary resource ' + String(res.uri ?? '') + ', ' + String(res.mimeType ?? '') + ']');
+            }
+            else {
+                parts.push(String(res.uri ?? ''));
+            }
+        }
+        else if (type === 'resource_link') {
+            parts.push(String(b.uri ?? b.name ?? ''));
+        }
+        else {
+            try {
+                parts.push(JSON.stringify(b));
+            }
+            catch {
+                parts.push(String(b));
+            }
+        }
+    }
+    const text = parts.filter((p) => p !== '').join(String.fromCharCode(10) + String.fromCharCode(10)).trim();
+    return formatResultString(text || '(MCP tool returned no content)', r.isError);
+}
+function formatResultString(result, isError) {
+    const text = typeof result === 'string' ? result : safeJson(result);
+    return isError ? 'MCP error: ' + text : text;
+}
+function safeJson(v) {
+    try {
+        const s = JSON.stringify(v);
+        return s === undefined ? String(v) : s;
+    }
+    catch {
+        return String(v);
+    }
+}
+// Namespacing: MCP tool names are prefixed with the server name, so the
+// system-prompt (and the transcript) show where a tool comes from and two
+// servers cannot collide. The prefix uses __ (double underscore) because
+// the model must be able to reproduce it exactly.
+export function qualifyToolName(server, tool) {
+    return server + '__' + tool.replace(/[^A-Za-z0-9_]/g, '_');
+}
+// Connect to ONE server and return a ready connection (or an error).
+async function connectServer(name, cfg, debug) {
+    try {
+        const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+        const client = new Client({ name: 'zames', version: '1.0.0' }, { capabilities: {} });
+        let transport;
+        if (cfg.url) {
+            if (cfg.transport === 'sse') {
+                const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
+                transport = new SSEClientTransport(new URL(cfg.url), {
+                    requestInit: cfg.headers ? { headers: cfg.headers } : undefined,
+                });
+            }
+            else {
+                const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
+                transport = new StreamableHTTPClientTransport(new URL(cfg.url), {
+                    requestInit: cfg.headers ? { headers: cfg.headers } : undefined,
+                });
+            }
+        }
+        else {
+            const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
+            transport = new StdioClientTransport({
+                command: String(cfg.command),
+                args: hardenPlaywrightArgs(String(cfg.command), cfg.args || []),
+                env: cfg.env,
+                cwd: cfg.cwd,
+                stderr: 'pipe',
+            });
+        }
+        await client.connect(transport);
+        const listed = await client.listTools();
+        const tools = (listed.tools || []).map((t) => {
+            const tool = t;
+            return {
+                name: String(tool.name),
+                description: String(tool.description || ''),
+                schema: tool.inputSchema,
+            };
+        });
+        debug?.(`MCP: connected to ${name} (${tools.length} tools)`);
+        return { name, client, tools };
+    }
+    catch (e) {
+        const msg = e.message || String(e);
+        debug?.(`MCP: failed to connect to ${name}: ${msg}`);
+        return { error: msg };
+    }
+}
+/**
+ * Build a pool from the MCP configs found for a workdir.
+ * Never throws: a broken server is reported in the status and skipped.
+ */
+export async function createMcpPool(opts) {
+    const files = await discoverConfigFiles(opts.workdir);
+    const config = await loadConfigFiles(files);
+    const servers = config.mcpServers || {};
+    const names = Object.keys(servers).filter((n) => !servers[n].disabled);
+    const infos = [];
+    const connections = [];
+    const tools = [];
+    for (const name of names) {
+        const cfg = servers[name];
+        const res = await connectServer(name, cfg, opts.debug);
+        if ('error' in res) {
+            infos.push({ name, tools: [], error: res.error });
+            continue;
+        }
+        connections.push(res);
+        infos.push({ name, tools: res.tools.map((t) => t.name) });
+        for (const tool of res.tools) {
+            const qualified = qualifyToolName(name, tool.name);
+            const params = jsonSchemaToParams(tool.schema);
+            const description = describeParamsExternally((tool.description || tool.name) + ` (MCP server: ${name})`, tool.schema);
+            tools.push({
+                name: qualified,
+                description,
+                parameters: params,
+                fn: async (args) => {
+                    try {
+                        const result = await res.client.callTool({
+                            name: tool.name,
+                            arguments: args,
+                        });
+                        return renderMcpResult(result);
+                    }
+                    catch (e) {
+                        return `MCP error (${name}/${tool.name}): ${e.message}`;
+                    }
+                },
+            });
+        }
+    }
+    let closed = false;
+    return {
+        tools,
+        status: () => ({
+            servers: infos,
+            toolCount: tools.length,
+        }),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            for (const c of connections) {
+                try {
+                    await c.client.close();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        },
+    };
+}

package/dist/system-prompt.js

@@ -113,6 +113,15 @@ You have access to the following tools:
 
 ${toolDescriptions}
 ${gitSection}${attachSection}${contextSection}
+## MCP tools
+
+Some tools are provided by external MCP servers and their names look
+like server__tool (for example playwright__browser_navigate). Treat
+them exactly like the built-in tools. A tool name with the __ separator
+and the (MCP server: ...) note in its description tells you which server
+it belongs to. The JSON Schema in the description lists the exact fields
+(including their descriptions and enums) - follow it.
+
 ## How to use tools
 
 To call ONE tool, respond with ONLY a JSON object (no markdown fences, no extra text):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Terminal coding agent over chat.deepseek.com via Playwright",
   "type": "module",
   "bin": {
@@ -36,6 +36,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "chalk": "^5.3.0",
     "cli-highlight": "^2.1.11",
     "markdansi": "^0.3.4",