Add MCP Registry Consumption Plan proposal

[JAORMX]

Summary

This PR adds a comprehensive proposal for how ToolHive will consume and run MCP servers from the official Model Context Protocol registry format.

What's Included

The proposal document (docs/proposals/toolhive-mcp-consumption-plan.md) covers:

🏗️ Architecture

• Unified registry abstraction layer for accessing both ToolHive and MCP registries
• Package resolver to convert MCP package definitions into Docker containers
• Security profile assignment system
• Metadata enrichment for community features

🔒 Security

• Default security profiles for unknown servers
• Permission prompting for elevated access
• Network isolation and filesystem restrictions
• Never allowing privileged mode

📦 Package Support

• Docker packages (direct execution)
• npm packages (via npx:// conversion)
• PyPI packages (via uvx:// conversion)
• NuGet packages (future support via dnx://)
• Remote SSE/HTTP servers (proxy connection)

📋 Implementation Plan

• Six-phase approach from foundation to launch
• Clear success criteria for each phase
• Risk analysis with mitigation strategies

Why This Matters

1. Ecosystem Growth: Enables ToolHive users to access the growing MCP ecosystem
2. Maintains Security: All servers run with ToolHive's security-first approach
3. Prevents Fragmentation: Supports both registry formats seamlessly
4. User Experience: Consistent interface regardless of server source

Changes Made

• Added new proposal document under docs/proposals/
• Fixed capitalization consistency (Toolhive → ToolHive) throughout the document
• Added periods to section purpose statements for consistency
• Ensured formatting aligns with existing proposal documents

Next Steps

Once approved, this proposal will guide the implementation of MCP registry consumption in ToolHive, starting with Phase 1 (Foundation) to understand and parse the MCP format.

[ChrisJBurns]

@claude Can you review this PR and the MCP registry proposal and offer your expertise on it

[claude]

Claude finished @ChrisJBurns's task —— View job

---

Comprehensive Review of MCP Registry Consumption Plan

I've thoroughly reviewed the proposal and ToolHive's existing architecture. Here's my detailed analysis:

Review Tasks:

• Read and analyze the proposal document
• Evaluate technical architecture approach
• Assess security model and implementation
• Review implementation phases and timeline
• Check alignment with existing ToolHive architecture
• Provide detailed feedback and recommendations

---

🎯 Overall Assessment: Excellent Proposal with Strategic Architecture

This proposal demonstrates deep understanding of both MCP ecosystem needs and ToolHive's security-first philosophy. The technical approach is sound and well-aligned with existing ToolHive patterns.

✅ Strengths

1. Strong Architectural Design

• Registry Abstraction Layer: Perfectly aligns with ToolHive's existing provider pattern in pkg/registry/provider.go. The current Provider interface can naturally extend to support multiple registry sources.
• Security-First Approach: The proposal maintains ToolHive's core security principles while enabling broader ecosystem access.
• Clean Separation of Concerns: Package resolver, security profile assignment, and metadata enrichment are well-separated components.

2. Excellent Security Model

• Default Deny: ProfileNone as default for unknown servers is correct and aligns with pkg/permissions/profile.go:101-115
• Docker Flag Filtering: The decision to ignore/validate Docker flags like --privileged, --volume is crucial for security (lines 108-141 in proposal)
• Permission Prompting: User consent for elevated permissions prevents silent privilege escalation

3. Pragmatic Package Strategy

The conversion strategy is well-thought-out:

Docker → Direct execution (optimal)
npm → npx:// conversion (leverages existing feature)
PyPI → uvx:// conversion (leverages existing feature)  
Remote → Proxy connection (already supported)

4. User Experience Considerations

• Registry source indicators prevent confusion
• Consistent CLI interface regardless of source
• Smart default selection with override options

🔍 Technical Deep-Dive Observations

Registry Integration

The proposal fits perfectly with ToolHive's existing registry architecture:

• Current ServerMetadata interface (lines 182-207 in pkg/registry/types.go) can represent both ToolHive and MCP servers
• The CustomMetadata map[string]any field (line 51) can store MCP-specific data
• Existing Provider interface can be extended for multiple sources

Security Alignment

The security model correctly builds on existing patterns:

• Uses ToolHive's permissions.Profile structure
• Respects network isolation via OutboundNetworkPermissions
• Maintains container-based isolation principles

📋 Recommendations & Areas for Enhancement

1. MCP Schema Versioning Strategy (High Priority)

The proposal mentions "version detection" but should elaborate on:

# How to handle schema evolution
mcp_registry:
  supported_versions: ["1.0", "1.1"] 
  fallback_behavior: "conservative_defaults"

2. Enhanced Security Profile Mapping

Consider category-based auto-profiling:

# Example mapping in implementation
category_profiles:
  "web-scraper": 
    base_profile: "network"
    prompt_for: ["filesystem_write"]
  "database-client":
    base_profile: "network_restricted" 
    allowed_ports: [3306, 5432, 27017]

3. Registry Priority and Fallback Logic

Clarify behavior when servers exist in multiple registries:

• ToolHive registry should take precedence (verified vs unverified)
• Clear user indication of source selection
• Option to override default priority

4. Performance Considerations

For Phase 3 implementation:

• Registry caching strategy (build on existing patterns in provider_remote.go)
• Batch operations for large MCP registries
• CDN/mirror support for package resolution

5. Metadata Schema Extensions

The existing CustomMetadata field can store MCP-specific data:

// Enhancement to existing types.go
type MCPMetadata struct {
    OriginalRegistryURL string   `json:"original_registry_url"`
    PackageType        string   `json:"package_type"` 
    ConversionMethod   string   `json:"conversion_method"`
    SecurityRisk       string   `json:"security_risk_level"`
}

🚨 Critical Security Considerations

Docker Runtime Arguments Handling

The proposal correctly identifies the need to filter Docker arguments, but should specify:

• Volume mounts: Require explicit approval with path validation
• Environment variables: Scan for secrets/credentials
• Network settings: Always override with ToolHive's network policy
• User/UID mapping: Maintain consistent security boundaries

Package Conversion Security

• npm packages: Validate package.json for suspicious scripts
• PyPI packages: Check for native extensions that could bypass containers
• Docker images: Scan for known vulnerabilities before execution

📊 Implementation Phase Assessment

The 6-phase approach is realistic:

• Phase 1-2: Foundation work is appropriate (2-3 months)
• Phase 3: Core implementation is the critical path (2-3 months)
• Phase 4: Security hardening is essential - don't skip (1-2 months)
• Phase 5-6: UX polish and launch (1-2 months)

Total timeline: 6-10 months - reasonable for this scope.

🔄 Integration with Existing Systems

The proposal integrates well with:

• ✅ Registry providers: Natural extension of existing abstractions
• ✅ Permission system: Builds on pkg/permissions/profile.go
• ✅ Transport layer: Reuses SSE/HTTP/stdio transports
• ✅ Container runtime: Leverages existing Docker integration

🎯 Final Recommendation

Strong approval for this proposal. The architecture is sound, security considerations are thorough, and the implementation plan is realistic. This will significantly expand ToolHive's ecosystem reach while maintaining its security-first principles.

Priority refinements for implementation:

1. Detailed MCP schema versioning strategy
2. Enhanced category-based security profiling
3. Clear registry priority/fallback mechanisms
4. Comprehensive security scanning for package conversions

This proposal positions ToolHive excellently to become the secure runtime platform for the entire MCP ecosystem.

---