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

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

@@ -1,190 +0,0 @@
-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

@@ -1,392 +0,0 @@
-#!/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

@@ -1,28 +0,0 @@
-/**
- * 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

@@ -1,86 +0,0 @@
-/**
- * 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,
-        },
-    };
-}