# MCP Server with Dynamic Per-User Tool Generation

A Model Context Protocol (MCP) server implementation using FastMCP that dynamically generates tools based on user permissions from an external API.

## Features

- **Dynamic Tool Generation**: Tools are generated at runtime based on user-specific schemas from an external API
- **Per-User Permissions**: Each authenticated user receives tools tailored to their permissions
- **Intelligent Caching**: Both API schemas and generated tools are cached with TTL for performance
- **Graceful Degradation**: Falls back to static tools if API is unavailable
- **Comprehensive Logging**: Detailed logging at INFO, DEBUG, WARNING, and ERROR levels
- **Thread-Safe**: Concurrent requests from multiple users are handled safely
- **Global Score Filtering**: Elasticsearch queries use global minScore threshold for result quality control

## Architecture

### Components

1. **`mcp_server.py`** - Main server entry point
   - Initializes FastMCP server
   - Registers static tools (add, echo, multiply)
   - Sets up dynamic tool middleware

2. **`api_client.py`** - External API integration
   - `FormSchemaClient`: Fetches and parses schemas from external API
   - `FormSchemaCache`: Caches API responses with TTL
   - Converts API field definitions to JSON Schema format

3. **`dynamic_tool_manager.py`** - Tool lifecycle management
   - `DynamicToolManager`: Manages per-user tool storage
   - Thread-safe caching with TTL
   - Cache statistics and invalidation

4. **`tool_function_factory.py`** - Dynamic function generation
   - Creates typed async functions from JSON schemas
   - Generates proper `inspect.Signature` for FastMCP validation
   - Maps JSON Schema types to Python types

5. **`tool_execution_handler.py`** - Tool execution backend
   - `ToolExecutionRouter`: Routes tool calls to appropriate handlers
   - Specialized handlers for different tool types
   - Structured error responses

6. **`dynamic_tool_middleware.py`** - FastMCP middleware
   - Intercepts `list/tools` requests
   - Extracts authentication tokens
   - Generates and caches user-specific tools
   - Returns combined static + dynamic tools

## Installation

1. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

2. **Configure the API URL:**
   Edit `mcp_server.py` and set the `FORM_SCHEMA_API_URL` to your external API endpoint:
   ```python
   FORM_SCHEMA_API_URL = "http://172.16.11.131/api/module/request/form"
   ```

## Usage

### Starting the Server

```bash
python mcp_server.py
```

The server will start on `http://127.0.0.1:9092/mcp`

### Authentication

The server expects authentication via HTTP `Authorization` header:

```
Authorization: Bearer <your-token>
```

The token is used to:
1. Fetch user-specific schema from the external API
2. Generate tools with fields the user has permission to access
3. Cache tools for subsequent requests

### Available Tools

#### Static Tools (Always Available)

- **`add(a: int, b: int) -> int`** - Adds two numbers
- **`echo(message: str) -> str`** - Echoes a message
- **`multiply(a: int, b: int) -> int`** - Multiplies two numbers

#### Dynamic Tools (User-Specific)

- **`create_request(...)`** - Creates a request with fields based on user permissions
  - Parameters are dynamically generated from the external API schema
  - Each user sees different parameters based on their permissions
  - Required fields, enums, and types are enforced

## How It Works

### Request Flow

1. **Client sends `list/tools` request** with `Authorization: Bearer <token>`

2. **Middleware intercepts the request:**
   - Extracts auth token from header
   - Checks if tools are cached for this user
   - If cached: Returns cached tools
   - If not cached: Proceeds to generation

3. **Tool Generation:**
   - Fetches schema from external API with user's token
   - Parses API response into JSON Schema
   - Creates typed async function with proper signature
   - Converts function to FastMCP `Tool` object
   - Caches the tool for future requests

4. **Response:**
   - Returns list of static tools + dynamic tools
   - Client sees tools specific to their permissions

### Tool Execution Flow

1. **Client calls `create_request` tool** with arguments

2. **FastMCP validates arguments** against the generated function signature

3. **Tool execution handler:**
   - Receives validated arguments
   - Processes the request
   - Returns structured response with ID, timestamp, status

## Configuration

### Cache TTL

Both schema cache and tool cache use 5-minute TTL by default. To change:

```python
# In mcp_server.py
schema_client = FormSchemaClient(
    api_url=FORM_SCHEMA_API_URL,
    cache_ttl=300,  # Change this value (seconds)
    verbose=True
)
tool_manager = DynamicToolManager(cache_ttl_seconds=300)  # Change this value
```

### Logging Level

To change logging verbosity:

```python
# In mcp_server.py
logging.basicConfig(
    level=logging.DEBUG,  # Change to DEBUG, INFO, WARNING, or ERROR
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```

## Testing

See `TEST_SCENARIOS.md` for comprehensive test scenarios including:

- User-specific tool generation
- Caching behavior
- Tool execution
- Error handling
- Validation enforcement

## API Schema Format

The external API should return a response with this structure:

```json
{
  "fieldList": [
    {
      "name": "Subject",
      "paramName": "subject",
      "type": "TextFieldRest",
      "required": true,
      "description": "Request subject",
      "groupIds": [1, 2],
      "hidden": false,
      "removed": false,
      "inActive": false
    }
  ]
}
```

Supported field types:
- `TextFieldRest` → `string`
- `NumberFieldRest` → `number`
- `DropDownFieldRest` → `string` with enum
- `MultiSelectDropDownFieldRest` → `array` of strings
- And more (see `api_client.py` for full mapping)

## Security Considerations

- Authentication tokens are truncated in logs and responses
- Tokens are validated on each request
- No token = static tools only (graceful degradation)
- FastMCP validates all tool arguments before execution

## Troubleshooting

### Server won't start
- Check that all dependencies are installed: `pip install -r requirements.txt`
- Verify Python version is 3.12+
- Check logs for import errors

### Tools not appearing
- Verify `Authorization` header is present and correctly formatted
- Check server logs for API fetch errors
- Ensure external API is accessible
- Verify user has permissions in the external system

### Cache not updating
- Default TTL is 5 minutes
- Manually clear cache: Call `tool_manager.clear_all_tools()` or restart server
- Check logs for cache hit/miss messages

## License

[Your License Here]

## Contributing

[Your Contributing Guidelines Here]