Tool Discovery System¶

Automatic detection and normalization of MCP server capabilities with support for multiple discovery strategies and protocols.

Overview¶

The MCP Platform tool discovery system provides comprehensive, automated detection of tools (capabilities) from MCP servers using multiple discovery strategies. It supports both the official MCP JSON-RPC over stdio protocol and fallback HTTP endpoints for broader compatibility.

Key Features¶

✅ MCP Protocol Compliant: Full support for MCP 2025-06-18 specification with JSON-RPC over stdio
🐳 Docker Integration: Direct discovery from Docker images with proper container lifecycle management
🔍 Multi-Strategy Discovery: Static, dynamic, template-based, and Docker probe strategies
📊 Rich CLI Interface: Beautiful, formatted output with comprehensive tool information
⚡ Caching Support: Optional caching for improved performance
🔄 Fallback Support: HTTP endpoint fallback for non-standard implementations

Discovery Strategies¶

1. MCP Protocol Discovery (Primary)¶

Uses the official MCP JSON-RPC protocol over stdio transport:

Initialize: Establishes MCP session with proper handshake
Tools/List: Retrieves comprehensive tool definitions with schemas
Normalization: Converts MCP tool definitions to unified format

2. Static Discovery¶

Reads tool definitions from tools.json files in template directories:

{
  "tools": [
    {
      "name": "example_tool",
      "description": "Example tool description",
      "category": "general",
      "parameters": {
        "type": "object",
        "properties": {
          "input": {"type": "string"}
        }
      }
    }
  ]
}

3. Dynamic Discovery (Fallback)¶

Probes HTTP endpoints for tool information: - /tools, /api/tools, /v1/tools, /mcp/tools - Supports various response formats

4. Template Fallback¶

Extracts capabilities from existing template.json definitions for compatibility.

CLI Usage¶

List Tools for Templates¶

# Basic tool discovery for deployed template
mcp-template tools demo

# Force refresh cached results
mcp-template tools demo --refresh

# Ignore cache entirely
mcp-template tools demo --no-cache

Template-Based Tool Discovery¶

The CLI now supports discovering tools directly from templates, with automatic Docker fallback for templates configured with tool_discovery: "dynamic":

# Discover tools from a template directory
mcp-template tools my-template

# With configuration values for Docker fallback
mcp-template tools my-template --config "PORT=8080,HOST=localhost"

# Force refresh template tool discovery
mcp-template tools my-template --refresh --config "DEBUG=true"

When a template has tool_discovery: "dynamic" in its configuration and standard discovery methods fail, the system automatically:

Checks for Docker image: Looks for docker_image and docker_tag in template config
Spins up container: Creates temporary container with provided config values as environment variables
Discovers tools: Uses MCP protocol or HTTP endpoints to discover available tools
Cleans up: Automatically removes the temporary container

Example template configuration supporting dynamic discovery:

{
  "name": "My MCP Server",
  "tool_discovery": "dynamic",
  "docker_image": "myregistry/mcp-server",
  "docker_tag": "latest",
  "config_schema": {
    "PORT": {"type": "integer", "default": 8080},
    "DEBUG": {"type": "boolean", "default": false}
  }
}

Discover Tools from Docker Images¶

# Discover from MCP filesystem server
mcp-template tools --image mcp/filesystem /tmp

# Discover from custom server with arguments
mcp-template tools --image myregistry/mcp-server:latest config.json --port 8080

# Example output for filesystem server
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                    🐳 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...                │
│ ...                  │ ...                                   │
└──────────────────────┴───────────────────────────────────────┘

Template Configuration¶

Configure tool discovery behavior in template.json:

{
  "name": "My MCP Server",
  "description": "An example MCP server template",
  "version": "1.0.0",
  "tool_discovery": {
    "method": "mcp_protocol",
    "fallback_methods": ["http", "static"],
    "cache_ttl": 300,
    "timeout": 30
  },
  "transport": {
    "default": "stdio",
    "supported": ["stdio", "http"]
  },
  "mcp_protocol": {
    "version": "2025-06-18",
    "capabilities": {
      "tools": {}
    }
  }
}

Configuration Fields¶

tool_discovery: Discovery method ("static", "dynamic", or "none")
"static": Uses pre-defined tools from tools.json file
"dynamic": Probes running server endpoints, with Docker fallback for templates
"none": Disables tool discovery
tool_endpoint: Custom endpoint for dynamic discovery (default: "/tools")
has_image: Whether the template has a Docker image for probing
docker_image: Docker image name for dynamic discovery fallback
docker_tag: Docker image tag (default: "latest")
config_schema: Schema for configuration values passed to Docker containers
origin: Template origin ("internal" or "external")

Static Tool Discovery¶

For static discovery, create a tools.json file in your template directory:

{
  "tools": [
    {
      "name": "hello_world",
      "description": "Generate a greeting message",
      "category": "greeting",
      "parameters": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name to greet"
          }
        }
      }
    }
  ],
  "metadata": {
    "discovery_method": "static",
    "last_updated": "2024-07-29T00:00:00Z"
  }
}

Dynamic Tool Discovery¶

For dynamic discovery, the system will probe these endpoints in order:

Custom endpoint (if specified in tool_endpoint)
/tools
/get_tools
/capabilities
/metadata
/openapi.json

The system expects responses in these formats:

Standard Tools Format¶

{
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "parameters": {...}
    }
  ]
}

Capabilities Format¶

{
  "capabilities": [
    {
      "name": "capability_name",
      "description": "Capability description"
    }
  ]
}

OpenAPI Format¶

{
  "paths": {
    "/api/endpoint": {
      "get": {
        "summary": "Endpoint description",
        "parameters": [...]
      }
    }
  }
}

Caching¶

Tool discovery results are automatically cached in ~/.mcp/cache/ for 6 hours by default.

Cache Management¶

from mcp_template.tools import CacheManager

cache = CacheManager()

# Get cache info
info = cache.get_cache_info()
print(f"Total files: {info['total_files']}")

# Clear expired entries
removed = cache.clear_expired()
print(f"Removed {removed} expired entries")

# Clear all cache
cache.clear_all()

Programmatic Usage¶

Tool Discovery¶

from mcp_template.tools import ToolDiscovery
from pathlib import Path

discovery = ToolDiscovery()

# Discover tools for a template
result = discovery.discover_tools(
    template_name="my-template",
    template_dir=Path("templates/my-template"),
    template_config={
        "tool_discovery": "static",
        "tool_endpoint": "/api/tools"
    },
    use_cache=True,
    force_refresh=False
)

print(f"Found {len(result['tools'])} tools")
for tool in result['tools']:
    print(f"- {tool['name']}: {tool['description']}")

Docker Probe¶

from mcp_template.tools import DockerProbe

probe = DockerProbe()

# Discover tools from Docker image
result = probe.discover_tools_from_image("myregistry/mcp-server:latest")

if result:
    print(f"Discovered {len(result['tools'])} tools from image")
else:
    print("Failed to discover tools")

Best Practices¶

Template Authors¶

Choose appropriate discovery method:
Use "static" for stable, well-defined tools
Use "dynamic" for servers with runtime tool generation
Use "none" only if tools cannot be discovered
Provide tools.json for static discovery:
Include comprehensive tool descriptions
Use consistent parameter schemas
Keep metadata up to date
Implement standard endpoints for dynamic discovery:
Prefer /tools endpoint with standard format
Include proper error handling and timeouts
Support JSON content negotiation

Platform Users¶

Use caching effectively:
Let cache work automatically for better performance
Use --refresh when you know tools have changed
Use --no-cache only for debugging
Monitor discovery results:
Check discovery method in tool listings
Verify tool counts and descriptions
Report issues with external templates

Error Handling¶

The system gracefully handles various error conditions:

Missing tools.json: Falls back to template.json or dynamic discovery
Network timeouts: Logs debug messages and continues with fallback
Invalid JSON: Logs warnings and skips malformed responses
Container failures: Automatically cleans up failed Docker containers

Extension Points¶

The system is designed for extensibility:

Custom Discovery Methods¶

class CustomToolDiscovery(ToolDiscovery):
    def _discover_custom_tools(self, template_name, config):
        # Implement custom discovery logic
        return {
            "tools": [...],
            "discovery_method": "custom",
            "timestamp": time.time()
        }

Custom Tool Formats¶

def normalize_custom_format(self, raw_data):
    # Convert custom format to standard tool format
    return [
        {
            "name": item["function_id"],
            "description": item["help_text"],
            "parameters": item["input_schema"]
        }
        for item in raw_data["functions"]
    ]

Troubleshooting¶

Common Issues¶

No tools discovered:
Check template configuration
Verify tools.json exists for static discovery
Test endpoints manually for dynamic discovery
Cache not working:
Check permissions on ~/.mcp/cache/
Verify cache timestamps
Use --no-cache to bypass temporarily
Docker probe failures:
Ensure Docker is running
Check image exists and is accessible
Verify container exposes HTTP endpoints
Timeout errors:
Check network connectivity
Verify server is responding
Consider increasing timeout values

Debug Mode¶

Enable debug logging to see detailed discovery process:

import logging
logging.basicConfig(level=logging.DEBUG)

Or set environment variable:

export LOG_LEVEL=DEBUG
mcp-template tools my-template