@agents-at-scale/ark 0.1.34 → 0.1.35-rc.1

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,
+        },
+    };
+}

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

@@ -0,0 +1,50 @@
+export interface ToolParameter {
+    name: string;
+    type?: string;
+}
+export interface DiscoveredTool {
+    name: string;
+    parameters: ToolParameter[];
+    return_type?: string;
+    docstring?: string;
+}
+export interface FileDiscoveryResult {
+    success: boolean;
+    file: string;
+    tools: DiscoveredTool[];
+    uses_fastmcp: boolean;
+    mcp_instance?: string;
+    server_name?: string;
+    error?: string;
+}
+export interface DirectoryDiscoveryResult {
+    directory: string;
+    files: FileDiscoveryResult[];
+    total_tools: number;
+    uses_fastmcp: boolean;
+}
+export type DiscoveryResult = FileDiscoveryResult | DirectoryDiscoveryResult;
+export interface ProjectDiscoveryResult {
+    path: string;
+    exists: boolean;
+    is_directory: boolean;
+    platform: 'python3' | null;
+    project_type: 'pyproject' | 'requirements' | null;
+    project_file: string | null;
+    project_name: string | null;
+    project_version: string | null;
+    has_fastmcp: boolean;
+    fastmcp_version: string | null;
+}
+export interface ProjectInfo {
+    path: string;
+    platform: 'python3';
+    projectType: 'pyproject' | 'requirements' | 'unknown';
+    hasVenv: boolean;
+    fastMCP: boolean;
+    fastMCPVersion?: string;
+}
+export interface ArkDevToolStatus extends ProjectInfo {
+    discovery?: DiscoveryResult;
+    tools: DiscoveredTool[];
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/lib/output.d.ts

@@ -0,0 +1,36 @@
+export type StatusType = 'success' | 'warning' | 'info' | 'error';
+declare const output: {
+    /**
+     * Display a status message with flexible formatting
+     */
+    statusMessage(type: StatusType, title: string, message?: string, ...args: unknown[]): void;
+    /**
+     * Display an error message with consistent formatting
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Display a success message with consistent formatting
+     */
+    success(message: string, ...args: unknown[]): void;
+    /**
+     * Display an info message (indented gray text)
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Display a warning message with consistent formatting
+     */
+    warning(message: string, ...args: unknown[]): void;
+    /**
+     * Display a status check item (like ark status format)
+     * @param status - 'found', 'missing', 'warning', 'error'
+     * @param label - The label to show (e.g., 'platform')
+     * @param value - The value in bright white (e.g., 'python3')
+     * @param details - Optional grey details
+     */
+    statusCheck(status: "found" | "missing" | "warning" | "error", label: string, value?: string, details?: string): void;
+    /**
+     * Display a section header (like 'ark services:')
+     */
+    section(title: string): void;
+};
+export default output;

package/dist/lib/output.js

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+const output = {
+    /**
+     * Display a status message with flexible formatting
+     */
+    statusMessage(type, title, message, ...args) {
+        const icons = {
+            success: chalk.green('✓'),
+            warning: chalk.yellow.bold('!'),
+            info: chalk.blue('ℹ'),
+            error: chalk.red('✗'),
+        };
+        const colors = {
+            success: chalk.green,
+            warning: chalk.yellow,
+            info: chalk.blue,
+            error: chalk.red,
+        };
+        const icon = icons[type];
+        const color = colors[type];
+        const logFn = type === 'error' ? console.error : console.log;
+        if (message) {
+            logFn(icon, color(`${title}:`), message, ...args);
+        }
+        else {
+            logFn(icon, title, ...args);
+        }
+    },
+    /**
+     * Display an error message with consistent formatting
+     */
+    error(message, ...args) {
+        this.statusMessage('error', 'error', message, ...args);
+    },
+    /**
+     * Display a success message with consistent formatting
+     */
+    success(message, ...args) {
+        this.statusMessage('success', message, undefined, ...args);
+    },
+    /**
+     * Display an info message (indented gray text)
+     */
+    info(message, ...args) {
+        console.log(chalk.gray(message), ...args);
+    },
+    /**
+     * Display a warning message with consistent formatting
+     */
+    warning(message, ...args) {
+        this.statusMessage('warning', 'warning', message, ...args);
+    },
+    /**
+     * Display a status check item (like ark status format)
+     * @param status - 'found', 'missing', 'warning', 'error'
+     * @param label - The label to show (e.g., 'platform')
+     * @param value - The value in bright white (e.g., 'python3')
+     * @param details - Optional grey details
+     */
+    statusCheck(status, label, value, details) {
+        const icons = {
+            found: chalk.green('✓'),
+            missing: chalk.yellow('?'),
+            warning: chalk.yellow('!'),
+            error: chalk.red('✗'),
+        };
+        const statusText = {
+            found: chalk.green(label),
+            missing: chalk.yellow(label),
+            warning: chalk.yellow(label),
+            error: chalk.red(label),
+        };
+        let output = `  ${icons[status]} ${statusText[status]}`;
+        if (value) {
+            output += ` ${chalk.bold.white(value)}`;
+        }
+        if (details) {
+            output += chalk.gray(` ${details}`);
+        }
+        console.log(output);
+    },
+    /**
+     * Display a section header (like 'ark services:')
+     */
+    section(title) {
+        console.log(chalk.cyan.bold(`${title}:`));
+    },
+};
+export default output;