@agents-at-scale/ark 0.1.35 → 0.1.36-rc1

package/dist/lib/dev/tools/analyzer.js

@@ -0,0 +1,190 @@
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export class ArkDevToolAnalyzer {
+    constructor() {
+        // The Python script is always adjacent to this file
+        // In dev: src/lib/dev/tools/discover_tools.py
+        // In prod: dist/lib/dev/tools/discover_tools.py (copied by postbuild)
+        this.discoverToolsScript = path.join(__dirname, 'discover_tools.py');
+    }
+    /**
+     * Analyze a tool directory and return its status
+     */
+    async analyzeToolDirectory(toolPath) {
+        const absolutePath = path.resolve(toolPath);
+        // Check if path exists
+        if (!fs.existsSync(absolutePath)) {
+            throw new Error(`Path not found: ${absolutePath}`);
+        }
+        // Get project info
+        const projectInfo = this.getProjectInfo(absolutePath);
+        // Discover tools using Python script
+        const discovery = await this.discoverTools(absolutePath);
+        // Extract all tools from discovery
+        const tools = this.extractTools(discovery);
+        return {
+            ...projectInfo,
+            discovery,
+            tools,
+        };
+    }
+    /**
+     * Get project information by checking for Python project files
+     */
+    getProjectInfo(dirPath) {
+        const info = {
+            path: dirPath,
+            platform: 'python3',
+            projectType: 'unknown',
+            hasVenv: false,
+            fastMCP: false,
+        };
+        // Check for virtual environment
+        info.hasVenv =
+            fs.existsSync(path.join(dirPath, '.venv')) ||
+                fs.existsSync(path.join(dirPath, 'venv'));
+        // Check Python project type and FastMCP presence
+        const pyprojectPath = path.join(dirPath, 'pyproject.toml');
+        const requirementsPath = path.join(dirPath, 'requirements.txt');
+        if (fs.existsSync(pyprojectPath)) {
+            info.projectType = 'pyproject';
+            const content = fs.readFileSync(pyprojectPath, 'utf-8');
+            if (content.includes('fastmcp')) {
+                info.fastMCP = true;
+                // Try to extract version
+                const versionMatch = content.match(/fastmcp[>=<~]*([0-9.]+)/);
+                if (versionMatch) {
+                    info.fastMCPVersion = versionMatch[1];
+                }
+            }
+        }
+        else if (fs.existsSync(requirementsPath)) {
+            info.projectType = 'requirements';
+            const content = fs.readFileSync(requirementsPath, 'utf-8');
+            if (content.includes('fastmcp')) {
+                info.fastMCP = true;
+                const versionMatch = content.match(/fastmcp[>=<~]*([0-9.]+)/);
+                if (versionMatch) {
+                    info.fastMCPVersion = versionMatch[1];
+                }
+            }
+        }
+        return info;
+    }
+    /**
+     * Discover project configuration
+     */
+    async discoverProject(targetPath) {
+        try {
+            // Check if Python is available
+            try {
+                execSync('python3 --version', { stdio: 'ignore' });
+            }
+            catch {
+                console.warn('Python 3 not found');
+                return undefined;
+            }
+            // Check if discover_tools.py exists
+            if (!fs.existsSync(this.discoverToolsScript)) {
+                console.warn(`discover_tools.py not found at ${this.discoverToolsScript}`);
+                return undefined;
+            }
+            // Run the discovery script with 'project' command
+            const result = execSync(`python3 "${this.discoverToolsScript}" project "${targetPath}"`, {
+                encoding: 'utf-8',
+                maxBuffer: 1024 * 1024, // 1MB buffer
+            });
+            return JSON.parse(result);
+        }
+        catch (error) {
+            console.error('Project discovery failed:', error);
+            return undefined;
+        }
+    }
+    /**
+     * Discover tools using the Python script
+     */
+    async discoverTools(targetPath) {
+        try {
+            // Check if Python is available
+            try {
+                execSync('python3 --version', { stdio: 'ignore' });
+            }
+            catch {
+                console.warn('Python 3 not found, skipping tool discovery');
+                return undefined;
+            }
+            // Check if discover_tools.py exists
+            if (!fs.existsSync(this.discoverToolsScript)) {
+                console.warn(`discover_tools.py not found at ${this.discoverToolsScript}`);
+                return undefined;
+            }
+            // Run the discovery script with 'tools' command
+            const result = execSync(`python3 "${this.discoverToolsScript}" tools "${targetPath}"`, {
+                encoding: 'utf-8',
+                maxBuffer: 1024 * 1024 * 10, // 10MB buffer
+            });
+            return JSON.parse(result);
+        }
+        catch (error) {
+            console.error('Tool discovery failed:', error);
+            return undefined;
+        }
+    }
+    /**
+     * Recursively find all MCP tools in a project
+     * This is a naive implementation that searches all Python files in the project tree
+     */
+    async findProjectTools(projectRoot) {
+        try {
+            // Check if Python is available
+            try {
+                execSync('python3 --version', { stdio: 'ignore' });
+            }
+            catch {
+                console.warn('Python 3 not found');
+                return null;
+            }
+            // Check if discover_tools.py exists
+            if (!fs.existsSync(this.discoverToolsScript)) {
+                console.warn(`discover_tools.py not found at ${this.discoverToolsScript}`);
+                return null;
+            }
+            // Run the discovery script with 'project-tools' command
+            const result = execSync(`python3 "${this.discoverToolsScript}" project-tools "${projectRoot}"`, {
+                encoding: 'utf-8',
+                maxBuffer: 1024 * 1024 * 10, // 10MB buffer
+            });
+            return JSON.parse(result);
+        }
+        catch (error) {
+            console.error('Project tools discovery failed:', error);
+            return null;
+        }
+    }
+    /**
+     * Extract all tools from discovery result
+     */
+    extractTools(discovery) {
+        if (!discovery)
+            return [];
+        // Check if it's a directory result
+        if ('files' in discovery) {
+            const dirResult = discovery;
+            const tools = [];
+            for (const file of dirResult.files) {
+                if (file.success && file.tools) {
+                    tools.push(...file.tools);
+                }
+            }
+            return tools;
+        }
+        // Single file result
+        const fileResult = discovery;
+        return fileResult.success ? fileResult.tools : [];
+    }
+}

package/dist/lib/dev/tools/discover_tools.py

@@ -0,0 +1,392 @@
+#!/usr/bin/env python3
+"""
+Discover MCP tools in Python files using static analysis.
+Uses only Python stdlib - no external dependencies required.
+"""
+
+import ast
+import json
+import sys
+import os
+from typing import Dict, List, Any
+
+
+class MCPToolDiscoverer(ast.NodeVisitor):
+    """AST visitor to find MCP tool definitions"""
+    
+    def __init__(self):
+        self.tools = []
+        self.mcp_var_name = None
+        self.imports = {}
+        self.current_function = None  # Track if we're inside a function
+        
+    def visit_ImportFrom(self, node):
+        """Track imports to identify FastMCP usage"""
+        if node.module == 'fastmcp':
+            for alias in node.names:
+                if alias.name == 'FastMCP':
+                    self.imports['FastMCP'] = alias.asname or alias.name
+        self.generic_visit(node)
+        
+    def visit_Assign(self, node):
+        """Find mcp = FastMCP(...) assignments"""
+        if len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
+            var_name = node.targets[0].id
+            if isinstance(node.value, ast.Call):
+                if isinstance(node.value.func, ast.Name):
+                    if node.value.func.id in self.imports.values():
+                        self.mcp_var_name = var_name
+                        # Extract server name if provided
+                        if node.value.args:
+                            if isinstance(node.value.args[0], ast.Constant):
+                                self.server_name = node.value.args[0].value
+        self.generic_visit(node)
+        
+    def visit_FunctionDef(self, node):
+        """Find functions decorated with @mcp.tool() - both at module level and nested"""
+        # Save the parent function context
+        parent_function = self.current_function
+        self.current_function = node.name
+        
+        # Check if this function is decorated as a tool
+        for decorator in node.decorator_list:
+            is_mcp_tool = False
+            tool_config = {}
+            
+            # Check for @mcp.tool() or @mcp.tool
+            if isinstance(decorator, ast.Call):
+                if isinstance(decorator.func, ast.Attribute):
+                    # Check for mcp.tool where mcp is a variable
+                    if (isinstance(decorator.func.value, ast.Name) and 
+                        decorator.func.value.id == self.mcp_var_name and
+                        decorator.func.attr == 'tool'):
+                        is_mcp_tool = True
+                        # Extract any config from @mcp.tool(name="...", description="...")
+                        for keyword in decorator.keywords:
+                            if isinstance(keyword.value, ast.Constant):
+                                tool_config[keyword.arg] = keyword.value.value
+            elif isinstance(decorator, ast.Attribute):
+                # Check for @mcp.tool without parentheses
+                if (isinstance(decorator.value, ast.Name) and 
+                    decorator.value.id == self.mcp_var_name and
+                    decorator.attr == 'tool'):
+                    is_mcp_tool = True
+                # Also check for @mcp.tool where mcp is a parameter (e.g., in register_tools(mcp))
+                elif (decorator.value.id if isinstance(decorator.value, ast.Name) else None) == 'mcp' and \
+                     decorator.attr == 'tool':
+                    is_mcp_tool = True
+                    
+            if is_mcp_tool:
+                tool_info = self.extract_function_info(node)
+                tool_info.update(tool_config)
+                if parent_function:
+                    tool_info['registered_in'] = parent_function
+                self.tools.append(tool_info)
+                
+        # Visit nested functions to find tools defined inside this function
+        self.generic_visit(node)
+        
+        # Restore parent function context
+        self.current_function = parent_function
+    
+    def visit_AsyncFunctionDef(self, node):
+        """Handle async functions the same way as regular functions"""
+        # Save the parent function context
+        parent_function = self.current_function
+        self.current_function = node.name
+        
+        # Check if this async function is decorated as a tool
+        for decorator in node.decorator_list:
+            is_mcp_tool = False
+            tool_config = {}
+            
+            # Check for @mcp.tool() or @mcp.tool
+            if isinstance(decorator, ast.Call):
+                if isinstance(decorator.func, ast.Attribute):
+                    if (isinstance(decorator.func.value, ast.Name) and 
+                        decorator.func.attr == 'tool'):
+                        # Could be mcp.tool where mcp is the var or a parameter
+                        if decorator.func.value.id == self.mcp_var_name or decorator.func.value.id == 'mcp':
+                            is_mcp_tool = True
+                            for keyword in decorator.keywords:
+                                if isinstance(keyword.value, ast.Constant):
+                                    tool_config[keyword.arg] = keyword.value.value
+            elif isinstance(decorator, ast.Attribute):
+                if decorator.attr == 'tool':
+                    # Could be @mcp.tool where mcp is the var or a parameter
+                    if isinstance(decorator.value, ast.Name):
+                        if decorator.value.id == self.mcp_var_name or decorator.value.id == 'mcp':
+                            is_mcp_tool = True
+                    
+            if is_mcp_tool:
+                tool_info = self.extract_function_info(node)
+                tool_info.update(tool_config)
+                if parent_function:
+                    tool_info['registered_in'] = parent_function
+                self.tools.append(tool_info)
+                
+        # Visit nested functions
+        self.generic_visit(node)
+        
+        # Restore parent function context
+        self.current_function = parent_function
+        
+    def extract_function_info(self, node):
+        """Extract function name, parameters, and docstring"""
+        info = {
+            'name': node.name,
+            'parameters': [],
+            'return_type': None,
+            'docstring': ast.get_docstring(node)
+        }
+        
+        # Extract parameters
+        for arg in node.args.args:
+            param = {'name': arg.arg}
+            if arg.annotation:
+                param['type'] = ast.unparse(arg.annotation) if hasattr(ast, 'unparse') else self.unparse_annotation(arg.annotation)
+            info['parameters'].append(param)
+            
+        # Extract return type
+        if node.returns:
+            info['return_type'] = ast.unparse(node.returns) if hasattr(ast, 'unparse') else self.unparse_annotation(node.returns)
+            
+        return info
+    
+    def unparse_annotation(self, annotation):
+        """Fallback for Python < 3.9 without ast.unparse"""
+        if isinstance(annotation, ast.Name):
+            return annotation.id
+        elif isinstance(annotation, ast.Constant):
+            return repr(annotation.value)
+        else:
+            return 'Any'
+
+
+def discover_tools_in_file(filepath):
+    """Discover MCP tools in a single Python file"""
+    try:
+        with open(filepath, 'r') as f:
+            content = f.read()
+            
+        tree = ast.parse(content)
+        discoverer = MCPToolDiscoverer()
+        discoverer.visit(tree)
+        
+        return {
+            'success': True,
+            'file': filepath,
+            'tools': discoverer.tools,
+            'uses_fastmcp': bool(discoverer.mcp_var_name),
+            'mcp_instance': discoverer.mcp_var_name,
+            'server_name': getattr(discoverer, 'server_name', None)
+        }
+    except SyntaxError as e:
+        return {
+            'success': False,
+            'file': filepath,
+            'error': f'Syntax error: {str(e)}',
+            'tools': []
+        }
+    except Exception as e:
+        return {
+            'success': False,
+            'file': filepath,
+            'error': str(e),
+            'tools': []
+        }
+
+
+def discover_tools_in_directory(dirpath):
+    """Discover MCP tools in Python files in root directory only (no recursion)"""
+    results = {
+        'directory': dirpath,
+        'files': [],
+        'total_tools': 0,
+        'uses_fastmcp': False
+    }
+    
+    # Only check Python files in the root directory
+    for file in os.listdir(dirpath):
+        if file.endswith('.py'):
+            filepath = os.path.join(dirpath, file)
+            if os.path.isfile(filepath):
+                file_result = discover_tools_in_file(filepath)
+                results['files'].append(file_result)
+                results['total_tools'] += len(file_result.get('tools', []))
+                if file_result.get('uses_fastmcp'):
+                    results['uses_fastmcp'] = True
+                    
+    return results
+
+
+def discover_project(dirpath):
+    """Discover project configuration and type"""
+    result = {
+        'path': dirpath,
+        'exists': os.path.exists(dirpath),
+        'is_directory': os.path.isdir(dirpath) if os.path.exists(dirpath) else False,
+        'platform': None,
+        'project_type': None,
+        'project_file': None,
+        'project_name': None,
+        'project_version': None,
+        'has_fastmcp': False,
+        'fastmcp_version': None
+    }
+    
+    if not result['exists']:
+        return result
+        
+    if not result['is_directory']:
+        return result
+    
+    # Check for Python project files
+    pyproject_path = os.path.join(dirpath, 'pyproject.toml')
+    requirements_path = os.path.join(dirpath, 'requirements.txt')
+    
+    if os.path.exists(pyproject_path):
+        result['platform'] = 'python3'
+        result['project_type'] = 'pyproject'
+        result['project_file'] = pyproject_path
+        
+        # Parse pyproject.toml
+        with open(pyproject_path, 'r') as f:
+            content = f.read()
+            
+            # Extract project name and version using basic parsing
+            # Look for [project] section
+            import re
+            
+            # Try to find name in [project] section
+            name_match = re.search(r'^\s*name\s*=\s*["\']([^"\']+)["\']', content, re.MULTILINE)
+            if name_match:
+                result['project_name'] = name_match.group(1)
+                
+            # Try to find version in [project] section
+            version_match = re.search(r'^\s*version\s*=\s*["\']([^"\']+)["\']', content, re.MULTILINE)
+            if version_match:
+                result['project_version'] = version_match.group(1)
+            
+            # Check for fastmcp
+            if 'fastmcp' in content:
+                result['has_fastmcp'] = True
+                version_match = re.search(r'fastmcp[>=<~]*([0-9.]+)', content)
+                if version_match:
+                    result['fastmcp_version'] = version_match.group(1)
+                    
+    elif os.path.exists(requirements_path):
+        result['platform'] = 'python3'
+        result['project_type'] = 'requirements'
+        result['project_file'] = requirements_path
+        
+        # Check for fastmcp
+        with open(requirements_path, 'r') as f:
+            content = f.read()
+            if 'fastmcp' in content:
+                result['has_fastmcp'] = True
+                import re
+                version_match = re.search(r'fastmcp[>=<~]*([0-9.]+)', content)
+                if version_match:
+                    result['fastmcp_version'] = version_match.group(1)
+    
+    return result
+
+
+def find_project_tools(project_root):
+    """
+    Naive recursive search for MCP tools in a Python project.
+    Searches all Python files in the project tree, excluding common non-source directories.
+    
+    This is intentionally naive - it doesn't try to be smart about which files to search,
+    it just excludes obvious non-source directories and searches everything else.
+    """
+    # Common directories to exclude from search
+    EXCLUDE_DIRS = {
+        'venv', '.venv', 'env', '.env', 'virtualenv',
+        'dist', 'build', '__pycache__', '.eggs', 'egg-info',
+        '.git', '.pytest_cache', '.mypy_cache', '.tox', 'htmlcov',
+        'node_modules', '.coverage', 'site-packages',
+        # Also exclude hidden directories
+    }
+    
+    results = {
+        'project_root': project_root,
+        'files_searched': 0,
+        'files_with_tools': 0,
+        'total_tools': 0,
+        'tools': [],
+        'errors': []
+    }
+    
+    for root, dirs, files in os.walk(project_root):
+        # Modify dirs in-place to skip excluded directories
+        dirs[:] = [d for d in dirs if d not in EXCLUDE_DIRS and not d.startswith('.')]
+        
+        # Process Python files in this directory
+        for file in files:
+            if file.endswith('.py'):
+                filepath = os.path.join(root, file)
+                results['files_searched'] += 1
+                
+                try:
+                    file_result = discover_tools_in_file(filepath)
+                    if file_result.get('success') and file_result.get('tools'):
+                        results['files_with_tools'] += 1
+                        for tool in file_result['tools']:
+                            # Add source file information to each tool
+                            tool['source_file'] = os.path.relpath(filepath, project_root)
+                            results['tools'].append(tool)
+                            results['total_tools'] += 1
+                except Exception as e:
+                    results['errors'].append({
+                        'file': os.path.relpath(filepath, project_root),
+                        'error': str(e)
+                    })
+    
+    return results
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            'error': 'Usage: discover_tools.py <command> <path>'
+        }))
+        sys.exit(1)
+    
+    command = sys.argv[1]
+    
+    if command == 'project':
+        if len(sys.argv) < 3:
+            print(json.dumps({'error': 'Path required for project discovery'}))
+            sys.exit(1)
+        path = sys.argv[2]
+        result = discover_project(path)
+    elif command == 'tools':
+        if len(sys.argv) < 3:
+            print(json.dumps({'error': 'Path required for tool discovery'}))
+            sys.exit(1)
+        path = sys.argv[2]
+        if os.path.isfile(path):
+            result = discover_tools_in_file(path)
+        elif os.path.isdir(path):
+            result = discover_tools_in_directory(path)
+        else:
+            result = {'error': f'Path not found: {path}'}
+    elif command == 'project-tools':
+        if len(sys.argv) < 3:
+            print(json.dumps({'error': 'Path required for project tools discovery'}))
+            sys.exit(1)
+        path = sys.argv[2]
+        if os.path.isdir(path):
+            result = find_project_tools(path)
+        else:
+            result = {'error': f'Path is not a directory: {path}'}
+    else:
+        result = {'error': f'Unknown command: {command}'}
+        
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/dist/lib/dev/tools/mcp-types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MCP Tool type utilities for discovered tools
+ * Uses the official Model Context Protocol types from @modelcontextprotocol/sdk
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export type { Tool as MCPTool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Convert a discovered Python tool to MCP format
+ */
+export declare function toMCPTool(discoveredTool: any): Tool;
+/**
+ * Format tool for OpenAI-compatible function calling
+ */
+export declare function toOpenAIFunction(tool: Tool): {
+    type: "function";
+    function: {
+        name: string;
+        description: string | undefined;
+        parameters: {
+            [x: string]: unknown;
+            type: "object";
+            properties?: {
+                [x: string]: unknown;
+            } | undefined;
+            required?: string[] | undefined;
+        };
+    };
+};

package/dist/lib/dev/tools/mcp-types.js

@@ -0,0 +1,86 @@
+/**
+ * MCP Tool type utilities for discovered tools
+ * Uses the official Model Context Protocol types from @modelcontextprotocol/sdk
+ */
+/**
+ * Convert a discovered Python tool to MCP format
+ */
+export function toMCPTool(discoveredTool) {
+    // Extract first line of docstring as description
+    const description = discoveredTool.docstring
+        ? discoveredTool.docstring.split('\n')[0].trim()
+        : undefined;
+    // Build properties from parameters
+    const properties = {};
+    const required = [];
+    if (discoveredTool.parameters) {
+        for (const param of discoveredTool.parameters) {
+            // Map Python types to JSON Schema types
+            let jsonType = 'string';
+            if (param.type) {
+                const pythonType = param.type.toLowerCase();
+                if (pythonType === 'int' || pythonType === 'float') {
+                    jsonType = 'number';
+                }
+                else if (pythonType === 'bool') {
+                    jsonType = 'boolean';
+                }
+                else if (pythonType.includes('list') ||
+                    pythonType.includes('array')) {
+                    jsonType = 'array';
+                }
+                else if (pythonType.includes('dict') || pythonType === 'object') {
+                    jsonType = 'object';
+                }
+            }
+            properties[param.name] = {
+                type: jsonType,
+                description: `Parameter ${param.name}`,
+            };
+            // For now, assume all parameters are required
+            // Could be enhanced to detect optional parameters
+            required.push(param.name);
+        }
+    }
+    // Build the base Tool object
+    const tool = {
+        name: discoveredTool.name,
+        title: toTitleCase(discoveredTool.name),
+        description,
+        inputSchema: {
+            type: 'object',
+            properties: Object.keys(properties).length > 0 ? properties : undefined,
+            required: required.length > 0 ? required : undefined,
+        },
+    };
+    // Add metadata if available
+    if (discoveredTool.source_file) {
+        tool.source_file = discoveredTool.source_file;
+    }
+    if (discoveredTool.registered_in) {
+        tool.registered_in = discoveredTool.registered_in;
+    }
+    return tool;
+}
+/**
+ * Convert snake_case to Title Case
+ */
+function toTitleCase(snakeCase) {
+    return snakeCase
+        .split('_')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * Format tool for OpenAI-compatible function calling
+ */
+export function toOpenAIFunction(tool) {
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+        },
+    };
+}