# Module Wrapper API Reference

Complete API documentation for all module wrapper and adapter tools in the FastMCP Google MCP Server.

## Overview

The Module Wrapper service provides Python module introspection, dynamic tool loading, and semantic search capabilities for development and debugging. This service enables real-time analysis of the codebase structure and intelligent code discovery.

## Available Tools

| Tool Name | Description |
|-----------|-------------|
| [`list_available_modules`](#list_available_modules) | List all available Python modules in the system |
| [`get_module_info`](#get_module_info) | Get detailed information about specific modules |
| [`search_module_functions`](#search_module_functions) | Search for functions across modules using semantic search |
| [`analyze_module_dependencies`](#analyze_module_dependencies) | Analyze module dependency relationships |
| [`get_adapter_system_status`](#get_adapter_system_status) | Check adapter system health and performance |

---

## Tool Details

### `list_available_modules`

List all Python modules available in the FastMCP Google MCP system with optional filtering.

**Parameters:**
- `pattern` (string, optional): Module name pattern to filter results
- `include_builtin` (boolean, optional, default: false): Include Python built-in modules
- `category_filter` (string, optional): Filter by module category (google_services, auth, tools, etc.)

**Module Categories:**
- **Google Services**: Gmail, Drive, Docs, Forms, Slides, Calendar, Sheets, Chat
- **Authentication**: OAuth, middleware, session management
- **Tools**: Utility functions and helper modules
- **Resources**: MCP resource providers
- **Middleware**: Service injection and management

**Response:**
- Array of module information including names, paths, and descriptions
- Module metadata including version and dependencies
- Load status and availability information
- Category classification and tags

### `get_module_info`

Retrieve comprehensive information about a specific Python module.

**Parameters:**
- `module_name` (string, required): Name of the module to analyze
- `include_functions` (boolean, optional, default: true): Include function definitions
- `include_classes` (boolean, optional, default: true): Include class definitions
- `include_dependencies` (boolean, optional, default: false): Include dependency analysis

**Module Analysis:**
- **Structure**: Classes, functions, constants, and variables
- **Documentation**: Docstrings and inline documentation
- **Dependencies**: Import relationships and requirements
- **Metadata**: Version, author, and package information
- **Code Metrics**: Lines of code, complexity analysis

**Response:**
- Complete module structure and organization
- Function and class signatures with documentation
- Import relationships and dependency tree
- Code quality metrics and analysis
- Usage examples and best practices

### `search_module_functions`

Search for functions across all modules using semantic similarity matching.

**Parameters:**
- `query` (string, required): Natural language search query
- `limit` (integer, optional, default: 10): Maximum number of results
- `score_threshold` (float, optional, default: 0.3): Minimum similarity score
- `module_filter` (string, optional): Restrict search to specific modules
- `include_private` (boolean, optional, default: false): Include private functions

**Semantic Search Capabilities:**
- Natural language function discovery
- Intent-based code search
- Cross-module function correlation
- Intelligent ranking and relevance

**Example Queries:**
```
"functions that send emails"
"authentication and OAuth handlers"
"file upload and Drive integration"
"calendar event creation"
"error handling and logging"
```

**Response:**
- Array of matching functions with similarity scores
- Function signatures and documentation
- Module location and context information
- Usage examples and related functions

### `analyze_module_dependencies`

Analyze dependency relationships between modules and identify potential issues.

**Parameters:**
- `target_module` (string, optional): Focus analysis on specific module
- `depth_limit` (integer, optional, default: 3): Maximum dependency depth to analyze
- `include_circular` (boolean, optional, default: true): Detect circular dependencies
- `include_external` (boolean, optional, default: true): Include external package dependencies

**Dependency Analysis:**
- **Import Graph**: Visual representation of module relationships
- **Circular Dependencies**: Detection and resolution suggestions
- **External Dependencies**: Third-party package requirements
- **Unused Imports**: Identification of unnecessary imports
- **Dependency Health**: Version conflicts and compatibility issues

**Response:**
- Dependency graph with relationship mapping
- Circular dependency detection results
- External package version analysis
- Optimization recommendations
- Security and compatibility warnings

### `get_adapter_system_status`

Check the health and performance status of the adapter system.

**Parameters:**
- None (system status check)

**System Metrics:**
- Module loading performance
- Memory usage and optimization
- Cache hit rates and efficiency
- Search index health and statistics
- Error rates and system stability

**Response:**
- Overall system health status
- Performance benchmarks and metrics
- Cache statistics and optimization data
- Error analysis and resolution suggestions
- System resource utilization

---

## Architecture

### Universal Module Wrapper System

The adapter system provides intelligent Python module introspection:

```mermaid
graph TB
    A[Module Discovery] --> B[Dynamic Loading]
    B --> C[Introspection Engine]
    C --> D[Semantic Indexing]
    D --> E[Search Optimization]
    E --> F[Caching Layer]
    F --> G[Query Interface]
```

### Intelligent Caching

Performance optimization through multi-layer caching:
- **Module Metadata**: Cached structure analysis
- **Function Signatures**: Pre-computed API information
- **Search Indices**: Semantic search optimization
- **Dependency Maps**: Relationship caching

### 30x Performance Improvement

The module wrapper system delivers revolutionary performance:
- **Startup Time**: Reduced from 3+ seconds to ~100ms
- **Module Loading**: Optimized lazy loading patterns
- **Search Performance**: Sub-millisecond semantic queries
- **Memory Efficiency**: Intelligent cache management

## Integration Features

### Development Workflow Enhancement

The adapter system enhances development productivity:

**Code Discovery:**
```python
# Find authentication-related functions
auth_functions = await search_module_functions(
    query="oauth authentication google login",
    limit=5,
    module_filter="auth"
)
```

**Dependency Analysis:**
```python
# Analyze Gmail service dependencies
gmail_deps = await analyze_module_dependencies(
    target_module="gmail.gmail_tools",
    include_circular=True
)
```

**Module Exploration:**
```python
# Get comprehensive module information
module_info = await get_module_info(
    module_name="drive.drive_tools",
    include_functions=True,
    include_dependencies=True
)
```

### Debugging and Troubleshooting

Advanced debugging capabilities:
- **Function Tracing**: Track function call relationships
- **Import Analysis**: Identify import-related issues
- **Performance Profiling**: Module loading performance analysis
- **Error Context**: Enhanced error reporting with module context

### Documentation Generation

Automated documentation capabilities:
- **API Documentation**: Auto-generated function documentation
- **Dependency Graphs**: Visual module relationship mapping
- **Usage Examples**: Context-aware code examples
- **Best Practices**: Intelligent coding recommendations

## Best Practices

### Module Organization
1. **Logical Grouping**: Organize modules by functionality
2. **Clear Dependencies**: Minimize circular dependencies
3. **Documentation**: Comprehensive docstrings and comments
4. **Testing**: Adequate test coverage for all modules

### Performance Optimization
1. **Lazy Loading**: Load modules only when needed
2. **Caching**: Leverage module metadata caching
3. **Import Management**: Optimize import statements
4. **Memory Usage**: Monitor and optimize memory consumption

### Development Workflow
1. **Code Discovery**: Use semantic search for function discovery
2. **Dependency Analysis**: Regular dependency health checks
3. **Refactoring**: Use dependency analysis for safe refactoring
4. **Documentation**: Leverage auto-generated documentation

## Advanced Features

### Semantic Code Analysis

The system provides intelligent code understanding:
- **Intent Recognition**: Understand developer queries
- **Context Awareness**: Consider module relationships
- **Code Similarity**: Identify similar functions and patterns
- **Usage Patterns**: Analyze common code usage patterns

### Dynamic Module Loading

Advanced module management capabilities:
- **Hot Reloading**: Dynamic module updates during development
- **Version Management**: Handle multiple module versions
- **Isolation**: Secure module loading and execution
- **Resource Management**: Efficient memory and CPU usage

### Integration with Google Services

Seamless integration with all Google Workspace services:
- **Service Discovery**: Automatic Google service module detection
- **API Mapping**: Intelligent API endpoint mapping
- **Authentication Integration**: Seamless auth module integration
- **Error Correlation**: Cross-service error analysis

## Common Use Cases

### Code Exploration and Learning
```python
# Discover Gmail-related functionality
gmail_functions = await search_module_functions(
    query="send email attachment gmail",
    limit=10,
    module_filter="gmail"
)

# Analyze module structure
gmail_info = await get_module_info(
    module_name="gmail.gmail_tools",
    include_functions=True,
    include_classes=True
)
```

### Dependency Management
```python
# Check system-wide dependencies
all_modules = await list_available_modules(
    category_filter="google_services"
)

# Analyze dependency health
for module in all_modules:
    deps = await analyze_module_dependencies(
        target_module=module["name"],
        include_circular=True
    )
```

### Development Debugging
```python
# Find authentication-related issues
auth_status = await get_adapter_system_status()
auth_modules = await search_module_functions(
    query="authentication error oauth failure",
    limit=5
)
```

## Error Handling

### Module Loading Errors
```json
{
  "error": {
    "code": "MODULE_LOAD_FAILED",
    "message": "Unable to load specified module",
    "details": {
      "module_name": "gmail.gmail_tools",
      "error_type": "ImportError",
      "missing_dependencies": ["google-auth"]
    }
  }
}
```

### Search Performance Issues
```json
{
  "error": {
    "code": "SEARCH_TIMEOUT",
    "message": "Semantic search operation timed out",
    "details": {
      "query": "complex search query",
      "timeout_ms": 5000,
      "suggestion": "Use more specific search terms"
    }
  }
}
```

### Dependency Resolution Failures
- **Circular Dependencies**: Detected and reported with resolution suggestions
- **Version Conflicts**: Package version incompatibilities identified
- **Missing Dependencies**: Required packages not found
- **Import Errors**: Module import failures with context

## Performance Monitoring

### System Metrics
- **Module Load Time**: Individual module loading performance
- **Search Response Time**: Semantic search query performance
- **Memory Usage**: Module memory consumption tracking
- **Cache Efficiency**: Hit/miss ratios and optimization opportunities

### Optimization Recommendations
- **Module Splitting**: Suggestions for large module refactoring
- **Import Optimization**: Unnecessary import identification
- **Caching Strategies**: Personalized caching recommendations
- **Performance Bottlenecks**: System performance issue identification

---

For more information, see:
- [Python Module Best Practices](../../PYTHON_MODULES.md)
- [Performance Optimization Guide](../../PERFORMANCE.md)
- [Development Workflow](../../DEVELOPMENT.md)
- [Main API Reference](../README.md)