lynkr 8.0.0 → 9.0.1

package/src/tools/code-mode.js

@@ -0,0 +1,304 @@
+/**
+ * Code Mode — Meta-Tools for MCP Token Optimization
+ *
+ * Replaces 100+ individual MCP tool definitions with 4 meta-tools,
+ * reducing tool-catalog token overhead from ~17,500 to ~700 tokens.
+ *
+ * Inspired by Bifrost's Code Mode. Instead of sending every MCP tool
+ * schema in every request, the LLM discovers tools lazily:
+ *   1. mcp_list_tools   → discover available tools (compact)
+ *   2. mcp_tool_info    → load full schema for one tool
+ *   3. mcp_tool_docs    → get usage examples
+ *   4. mcp_execute      → execute a tool by name
+ *
+ * Activation: CODE_MODE_ENABLED=true
+ *
+ * @module tools/code-mode
+ */
+
+const { registerTool } = require('.');
+const { listServers, ensureClient } = require('../mcp');
+const config = require('../config');
+const logger = require('../logger');
+
+// ── Tool List Cache ─────────────────────────────────────────────────
+
+let toolListCache = null;
+let toolListCacheTs = 0;
+
+function getCacheTtl() {
+  return config.mcp?.codeMode?.toolListCacheTtl || 60_000;
+}
+
+/**
+ * Fetch tool lists from all MCP servers, with caching.
+ * @param {string} [filterServerId] - Optional: only fetch from this server
+ * @param {boolean} [forceRefresh] - Bypass cache
+ * @returns {Promise<Object>} { serverId: [{ name, description }] }
+ */
+async function fetchToolList(filterServerId, forceRefresh = false) {
+  const now = Date.now();
+  if (!forceRefresh && toolListCache && (now - toolListCacheTs < getCacheTtl())) {
+    if (filterServerId) {
+      return { [filterServerId]: toolListCache[filterServerId] || [] };
+    }
+    return toolListCache;
+  }
+
+  const servers = listServers();
+  const result = {};
+
+  await Promise.all(
+    servers.map(async (server) => {
+      if (filterServerId && server.id !== filterServerId) return;
+      try {
+        const client = await ensureClient(server.id);
+        if (!client) {
+          result[server.id] = { error: 'Server not available' };
+          return;
+        }
+        const response = await client.request('tools/list', {});
+        const tools = Array.isArray(response?.tools) ? response.tools : [];
+        result[server.id] = tools.map(t => ({
+          name: t.name ?? t.method ?? 'unknown',
+          description: (t.description || '').substring(0, 100),
+        }));
+      } catch (err) {
+        result[server.id] = { error: err.message };
+      }
+    })
+  );
+
+  // Update cache if we fetched all servers
+  if (!filterServerId) {
+    toolListCache = result;
+    toolListCacheTs = now;
+  }
+
+  return filterServerId ? { [filterServerId]: result[filterServerId] || [] } : result;
+}
+
+/**
+ * Fetch full tool schema for a specific tool on a specific server.
+ * @param {string} serverId
+ * @param {string} toolName
+ * @returns {Promise<Object|null>}
+ */
+async function fetchToolSchema(serverId, toolName) {
+  const client = await ensureClient(serverId);
+  if (!client) return null;
+
+  const response = await client.request('tools/list', {});
+  const tools = Array.isArray(response?.tools) ? response.tools : [];
+  return tools.find(t => (t.name ?? t.method) === toolName) || null;
+}
+
+/**
+ * Generate a usage example from a tool's input schema.
+ * @param {Object} tool - Tool definition with inputSchema
+ * @returns {string} Example JSON
+ */
+function generateExample(tool) {
+  const schema = tool.inputSchema || tool.input_schema || {};
+  const props = schema.properties || {};
+  const example = {};
+
+  for (const [key, def] of Object.entries(props)) {
+    if (def.type === 'string') example[key] = def.example || `<${key}>`;
+    else if (def.type === 'number' || def.type === 'integer') example[key] = def.example || 0;
+    else if (def.type === 'boolean') example[key] = def.example ?? true;
+    else if (def.type === 'array') example[key] = [];
+    else if (def.type === 'object') example[key] = {};
+    else example[key] = null;
+  }
+
+  return JSON.stringify(example, null, 2);
+}
+
+// ── Meta-Tool Registration ──────────────────────────────────────────
+
+function registerCodeModeTools() {
+  // 1. mcp_list_tools — discover available tools
+  registerTool(
+    'mcp_list_tools',
+    async ({ args = {} }) => {
+      const serverId = args.server_id || null;
+      const forceRefresh = args.force_refresh === true;
+      const result = await fetchToolList(serverId, forceRefresh);
+
+      // Add summary stats
+      let totalTools = 0;
+      for (const tools of Object.values(result)) {
+        if (Array.isArray(tools)) totalTools += tools.length;
+      }
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({ total_tools: totalTools, servers: result }, null, 2),
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'List all available MCP tools across all servers. Returns tool names and brief descriptions. Use this first to discover what tools are available.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'Optional: filter to a specific MCP server ID' },
+          force_refresh: { type: 'boolean', description: 'Bypass cache and refresh tool list' },
+        },
+      },
+    }
+  );
+
+  // 2. mcp_tool_info — load full schema for one tool
+  registerTool(
+    'mcp_tool_info',
+    async ({ args = {} }) => {
+      const serverId = args.server_id;
+      const toolName = args.tool_name;
+
+      if (!serverId || !toolName) {
+        throw new Error('mcp_tool_info requires server_id and tool_name');
+      }
+
+      const tool = await fetchToolSchema(serverId, toolName);
+      if (!tool) {
+        throw new Error(`Tool "${toolName}" not found on server "${serverId}"`);
+      }
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({
+          server: serverId,
+          name: tool.name ?? tool.method,
+          description: tool.description || '',
+          inputSchema: tool.inputSchema || tool.input_schema || {},
+        }, null, 2),
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'Get the full schema and detailed description for a specific MCP tool. Use after mcp_list_tools to get the exact parameters needed before calling mcp_execute.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'MCP server ID' },
+          tool_name: { type: 'string', description: 'Tool name from mcp_list_tools' },
+        },
+        required: ['server_id', 'tool_name'],
+      },
+    }
+  );
+
+  // 3. mcp_tool_docs — usage examples
+  registerTool(
+    'mcp_tool_docs',
+    async ({ args = {} }) => {
+      const serverId = args.server_id;
+      const toolName = args.tool_name;
+
+      if (!serverId || !toolName) {
+        throw new Error('mcp_tool_docs requires server_id and tool_name');
+      }
+
+      const tool = await fetchToolSchema(serverId, toolName);
+      if (!tool) {
+        throw new Error(`Tool "${toolName}" not found on server "${serverId}"`);
+      }
+
+      const schema = tool.inputSchema || tool.input_schema || {};
+      const params = Object.entries(schema.properties || {}).map(([name, def]) => ({
+        name,
+        type: def.type || 'any',
+        required: (schema.required || []).includes(name),
+        description: def.description || '',
+      }));
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({
+          server: serverId,
+          tool: tool.name ?? tool.method,
+          description: tool.description || '',
+          parameters: params,
+          example_arguments: generateExample(tool),
+          usage: `Use mcp_execute with server_id="${serverId}", tool_name="${toolName}", and arguments matching the schema above.`,
+        }, null, 2),
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'Get usage documentation, parameter details, and example arguments for an MCP tool.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'MCP server ID' },
+          tool_name: { type: 'string', description: 'Tool name' },
+        },
+        required: ['server_id', 'tool_name'],
+      },
+    }
+  );
+
+  // 4. mcp_execute — execute a tool by name
+  registerTool(
+    'mcp_execute',
+    async ({ args = {} }) => {
+      const serverId = args.server_id;
+      const toolName = args.tool_name;
+      const toolArgs = args.arguments ?? {};
+
+      if (!serverId || !toolName) {
+        throw new Error('mcp_execute requires server_id and tool_name');
+      }
+
+      const client = await ensureClient(serverId.trim());
+      if (!client) {
+        throw new Error(`MCP server "${serverId}" is not available.`);
+      }
+
+      const result = await client.request(toolName.trim(), toolArgs);
+
+      return {
+        ok: true,
+        status: 200,
+        content: JSON.stringify({
+          server: serverId,
+          tool: toolName,
+          result,
+        }, null, 2),
+        metadata: { server: serverId, tool: toolName },
+      };
+    },
+    {
+      category: 'code-mode',
+      description: 'Execute an MCP tool by name with JSON arguments. First use mcp_list_tools to discover tools, then mcp_tool_info to get the schema, then this tool to execute.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          server_id: { type: 'string', description: 'MCP server ID' },
+          tool_name: { type: 'string', description: 'Tool method name' },
+          arguments: {
+            type: 'object',
+            description: 'JSON arguments matching the tool input schema',
+            additionalProperties: true,
+          },
+        },
+        required: ['server_id', 'tool_name'],
+      },
+    }
+  );
+
+  logger.info('[code-mode] Registered 4 meta-tools: mcp_list_tools, mcp_tool_info, mcp_tool_docs, mcp_execute');
+}
+
+module.exports = {
+  registerCodeModeTools,
+  // Exported for testing
+  fetchToolList,
+  fetchToolSchema,
+  generateExample,
+};

package/src/tools/index.js

@@ -30,6 +30,10 @@ const TOOL_ALIASES = {
   WebSearch: "web_search",
   web_fetch: "web_fetch",
   webfetch: "web_fetch",
+  web_agent: "web_agent",
+  webagent: "web_agent",
+  WebAgent: "web_agent",
+  tinyfish: "web_agent",
   task: "fs_write",
   write: "fs_write",
   filewrite: "fs_write",

package/src/tools/lazy-loader.js

@@ -57,6 +57,11 @@ const TOOL_CATEGORIES = {
     loader: () => require('./tasks').registerTaskTools,
     priority: 2,
   },
+  tinyfish: {
+    keywords: ['tinyfish', 'web_agent', 'automate', 'scrape', 'extract', 'crawl', 'browser'],
+    loader: () => require('./tinyfish').registerTinyFishTools,
+    priority: 2,
+  },
   tests: {
     keywords: ['test', 'jest', 'mocha', 'pytest', 'unittest', 'spec', 'coverage', 'assert'],
     loader: () => require('./tests').registerTestTools,
@@ -72,6 +77,11 @@ const TOOL_CATEGORIES = {
     loader: () => require('./agent-task').registerAgentTaskTool,
     priority: 2,
   },
+  'code-mode': {
+    keywords: ['mcp', 'execute', 'server', 'tool', 'code mode'],
+    loader: () => require('./code-mode').registerCodeModeTools,
+    priority: 3,
+  },
 };
 
 /**
@@ -276,7 +286,15 @@ function loadCategoryForTool(toolName) {
     'workspace_sandbox_sessions': 'mcp',
     'workspace_mcp_servers': 'mcp',
 
+    // Code Mode meta-tools
+    'mcp_list_tools': 'code-mode',
+    'mcp_tool_info': 'code-mode',
+    'mcp_tool_docs': 'code-mode',
+    'mcp_execute': 'code-mode',
+
     // Agent task
+    // TinyFish (web agent)
+    'web_agent': 'tinyfish',
     'agent_task': 'agentTask',
   };
 

package/src/tools/mcp-remote.js

@@ -1,5 +1,6 @@
 const { registerTool } = require(".");
 const { listServers, ensureClient } = require("../mcp");
+const config = require("../config");
 const logger = require("../logger");
 
 const REMOTE_TOOL_PREFIX = "mcp";
@@ -12,6 +13,12 @@ function sanitiseName(value) {
 }
 
 async function registerRemoteTools() {
+  // Code Mode: register 4 meta-tools instead of individual remote tools
+  if (config.mcp?.codeMode?.enabled) {
+    const { registerCodeModeTools } = require("./code-mode");
+    registerCodeModeTools();
+    return;
+  }
   const servers = listServers();
   await Promise.all(
     servers.map(async (server) => {

package/src/tools/smart-selection.js

@@ -316,6 +316,17 @@ function selectToolsSmartly(tools, classification, options = {}) {
     selectedTools = selectedTools.filter(t => minimalTools.includes(t.name));
   }
 
+  // Code Mode: always include the 4 meta-tools (only ~700 tokens total)
+  const codeConfig = require('../config');
+  if (codeConfig.mcp?.codeMode?.enabled) {
+    const codeModeNames = new Set(['mcp_list_tools', 'mcp_tool_info', 'mcp_tool_docs', 'mcp_execute']);
+    for (const tool of tools) {
+      if (codeModeNames.has(tool.name) && !selectedTools.some(t => t.name === tool.name)) {
+        selectedTools.push(tool);
+      }
+    }
+  }
+
   return selectedTools;
 }