# [DEPRECATED] discover-tools

**[DEPRECATED] Use `tools --image` instead under the interactive CLI. This command will be removed in a future version.**

⚠️ **This command is deprecated**. The functionality has been merged into the unified `tools` command.

**Migration**: Replace `discover-tools --image` with `tools --image`:

```bash
# Old (deprecated)
mcpt discover-tools --image mcp/filesystem /tmp

# New (recommended)
mcpt> tools --image mcp/filesystem /tmp
```

---

## Synopsis

```bash
mcpt discover-tools --image IMAGE [SERVER_ARGS...]
```

## Description

The `discover-tools` command probes Docker images to discover MCP server capabilities using the official MCP JSON-RPC over stdio protocol. It automatically handles container lifecycle management, protocol negotiation, and presents results in a beautiful, formatted interface.

This command is particularly useful for:
- **Evaluating MCP servers** before deployment
- **Understanding available tools** and their capabilities
- **Debugging MCP server implementations**
- **Generating integration documentation**

## Options

| Option | Description | Required |
|--------|-------------|----------|
| `--image IMAGE` | Docker image name to probe | Yes |
| `SERVER_ARGS` | Arguments to pass to the MCP server | No |

## MCP Protocol Support

The tool discovery system uses the official MCP 2025-06-18 specification:

1. **Initialize**: Establishes MCP session with proper handshake
2. **Tools/List**: Retrieves comprehensive tool definitions
3. **Normalization**: Converts to unified format for display

### Fallback Strategy

If MCP stdio fails, the system automatically falls back to:
- HTTP endpoint probing (`/tools`, `/api/tools`, etc.)
- Static tool definition discovery
- Template metadata extraction

## Examples

### Basic Discovery

```bash
# Discover tools from filesystem server
mcpt discover-tools --image mcp/filesystem /tmp

# Example output:
╭──────────────────────────────────────────────────────────────╮
│                    🐳 Docker Tool Discovery                  │
╰──────────────────────────────────────────────────────────────╯

✅ Discovered 11 tools via docker_mcp_stdio

┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool Name            ┃ Description                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ read_file            │ Read complete file contents...       │
│ write_file           │ Create or overwrite files...         │
│ list_directory       │ List directory contents...           │
│ create_directory     │ Create directories...                │
│ directory_tree       │ Get recursive tree view...           │
│ move_file            │ Move or rename files...              │
│ search_files         │ Search for files by pattern...       │
│ get_file_info        │ Get detailed file metadata...        │
│ edit_file            │ Make line-based edits...             │
│ read_multiple_files  │ Read multiple files efficiently...   │
│ list_allowed_directories │ List accessible directories...   │
└──────────────────────┴───────────────────────────────────────┘

💡 Usage Example:
  from mcp_template.tools.mcp_client_probe import MCPClientProbe
  client = MCPClientProbe()
  result = client.discover_tools_from_docker_sync('mcp/filesystem', ['/tmp'])
```

### Custom MCP Servers

```bash
# Database server with connection parameters
mcpt discover-tools \
  --image myregistry/postgres-mcp:latest \
  --host localhost --port 5432 --database mydb

# API server with authentication
mcpt discover-tools \
  --image company/api-mcp:v1.0 \
  --api-key $API_TOKEN --base-url https://api.example.com

# File server with multiple directories
mcpt discover-tools \
  --image mcp/filesystem \
  /data /workspace /tmp
```

### Advanced Examples

```bash
# Custom image with complex configuration
mcpt discover-tools \
  --image custom/research-mcp:latest \
  --config config.json \
  --model gpt-4 \
  --research-dir /research \
  --output-format json

# Development server with debug mode
mcpt discover-tools \
  --image local/dev-mcp:latest \
  --debug \
  --log-level trace \
  --dev-mode
```

## Output Format

The command provides rich, structured output including:

### Tool Information
- **Name**: Tool identifier for calling
- **Description**: Human-readable explanation
- **Category**: Tool classification (mcp, general, etc.)
- **Parameters**: JSON schema for input validation

### Discovery Metadata
- **Discovery Method**: How tools were discovered (mcp_stdio, http, static)
- **Server Information**: MCP server name and version
- **Command Used**: Exact Docker command executed
- **Timestamp**: When discovery was performed

### Usage Examples
- **MCP Client Code**: Python code snippets for tool usage
- **Integration Examples**: Ready-to-use integration patterns
- **Error Handling**: Common error scenarios and solutions

## JSON Output

For programmatic usage, pipe to `jq` or similar tools:

```bash
# Get raw JSON data
mcpt discover-tools --image mcp/filesystem /tmp | \
  grep -A 1000 "Raw result:" | tail -n +2

# Extract just tool names
mcpt discover-tools --image mcp/filesystem /tmp 2>/dev/null | \
  jq -r '.tools[].name'

# Get tools with descriptions
mcpt discover-tools --image mcp/filesystem /tmp 2>/dev/null | \
  jq -r '.tools[] | "\(.name): \(.description)"'
```

## Container Management

The discovery process automatically handles:
- **Container Creation**: Temporary containers with unique names
- **Lifecycle Management**: Automatic cleanup on success or failure
- **Resource Limits**: Appropriate CPU and memory constraints
- **Network Isolation**: Secure container networking
- **Timeout Handling**: Graceful termination after timeout

## Troubleshooting

### Common Issues

#### Image Not Found
```bash
❌ Docker image 'nonexistent/image' not found
```
**Solution**: Verify image exists and you have pull permissions.

#### MCP Protocol Errors
```bash
❌ MCP initialization failed: Expecting value: line 1 column 1 (char 0)
```
**Solutions**:
- Ensure image implements MCP protocol correctly
- Check if image requires specific arguments
- Try with different server arguments

#### Permission Errors
```bash
❌ Permission denied: Cannot access /restricted
```
**Solution**: Use accessible directories or configure image permissions.

#### Timeout Errors
```bash
❌ Timeout waiting for MCP response (30s)
```
**Solutions**:
- Server may be slow to start - this is normal for complex servers
- Check if server arguments are correct
- Verify image is functioning properly

### Debug Mode

For detailed troubleshooting information:

```bash
# Enable debug logging
MCP_DEBUG=1 mcpt discover-tools --image mcp/filesystem /tmp

# Check container logs manually
docker run -it --rm mcp/filesystem /tmp
# Then manually send MCP commands via stdin
```

## Integration with Templates

Use discovered tools to inform template creation:

```bash
# Discover tools
mcpt discover-tools --image custom/mcp-server:latest > tools.json

# Create template with discovered capabilities
mcpt create my-template --from-discovery tools.json

# Deploy template
mcpt deploy my-template
```

## Performance Considerations

- **Container Startup**: First run may be slower due to image pull
- **Caching**: Subsequent runs with same image are faster
- **Parallel Discovery**: Can run multiple discoveries simultaneously
- **Resource Usage**: Minimal overhead, containers are ephemeral

## Security Notes

- **Container Isolation**: Discovery runs in isolated containers
- **Network Access**: Limited network access during discovery
- **File System**: No persistent changes to host system
- **Cleanup**: Automatic cleanup prevents resource leaks

## See Also

- [tools](tools.md) - **NEW**: Unified command for listing tools from templates and Docker images
- [deploy](deploy.md) - Deploy templates after discovery
- [connect](connect.md) - Generate integration examples
- [Tool Discovery System](../tool-discovery.md) - Technical details

## Migration Guide

This command has been deprecated in favor of the unified `tools` command:

| Old Command | New Command |
|-------------|-------------|
| `discover-tools --image IMAGE` | `tools --image IMAGE` |
| `discover-tools --image IMAGE arg1 arg2` | `tools --image IMAGE arg1 arg2` |

All functionality, options, and behavior remain exactly the same.
