library-implementation-principles
Guidelines for implementing generalizable solutions in the penguiflow library. Use when modifying library code, adding features, or fixing bugs in penguiflow core.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for implementing generalizable and extensible solutions within the penguiflow library. It focuses on core architectural principles such as avoiding hardcoded logic, implementing robust transport detection for MCP (Model Context Protocol), and ensuring universal authentication support. By following these guidelines, developers can maintain a flexible codebase where behavior is driven by configuration rather than static code, ensuring the library remains scalable and easy to maintain.
Use Cases
- Refactoring core library modules to support multiple authentication types (API Key, Bearer, OAuth2) using a unified handler pattern.
- Adding new tool transports to the framework while ensuring they are automatically detected or explicitly configurable via ExternalToolConfig.
- Conducting technical code reviews to ensure new features or bug fixes adhere to the 'Generalizability' principle and avoid use-case-specific hardcoding.
- Designing new library features that require configuration-driven behavior to support diverse environment requirements without modifying the core logic.
| name | library-implementation-principles |
|---|---|
| description | Guidelines for implementing generalizable solutions in the penguiflow library. Use when modifying library code, adding features, or fixing bugs in penguiflow core. |
Library Implementation Principles
Core Principle: Generalizability
When solving specific issues in the penguiflow library, implementations MUST be generalizable. Never hardcode solutions for specific use cases.
Anti-Pattern Examples
Bad: Hardcoding Transport Type
# WRONG - Forces StreamableHTTP for all URL-based connections
if connection.startswith(("http://", "https://")):
transport = StreamableHttpTransport(url=connection, headers=auth_headers)
Bad: Assuming Auth Mechanism
# WRONG - Only handles one auth type at connection time
if self.config.auth_type == AuthType.BEARER:
# handle bearer
# Missing: API_KEY, COOKIE, OAUTH2_USER, custom auth
Correct Patterns
1. Transport Detection
FastMCP supports multiple transports - let it detect or make it configurable:
# GOOD - Configurable MCP transport mode (in config.py)
class McpTransportMode(str, Enum):
"""MCP transport mode for URL-based connections."""
AUTO = "auto" # Let FastMCP auto-detect (default when no auth headers)
SSE = "sse" # Force Server-Sent Events transport (legacy)
STREAMABLE_HTTP = "streamable_http" # Force Streamable HTTP (modern)
class ExternalToolConfig(BaseModel):
# ...
mcp_transport_mode: McpTransportMode = Field(
default=McpTransportMode.AUTO,
description="For MCP over HTTP: auto-detect, sse, or streamable_http",
)
# GOOD - In ToolNode._resolve_mcp_url_transport()
def _resolve_mcp_url_transport(self, connection, auth_headers, sse_cls, streamable_cls):
mode = self.config.mcp_transport_mode
# Explicit SSE mode
if mode == McpTransportMode.SSE:
return sse_cls(url=connection, headers=auth_headers or {})
# Explicit StreamableHTTP mode
if mode == McpTransportMode.STREAMABLE_HTTP:
return streamable_cls(url=connection, headers=auth_headers or {})
# AUTO mode without auth - let FastMCP auto-detect
if not auth_headers:
return connection
# AUTO mode with auth - detect from URL pattern
if "/sse" in connection.lower():
return sse_cls(url=connection, headers=auth_headers)
return streamable_cls(url=connection, headers=auth_headers)
2. Auth Type Extensibility
Support all auth types uniformly:
# GOOD - Extensible auth resolution
class AuthType(str, Enum):
NONE = "none"
API_KEY = "api_key"
BEARER = "bearer"
COOKIE = "cookie"
OAUTH2_USER = "oauth2_user"
CUSTOM = "custom" # For custom auth handlers
def _get_auth_headers(self) -> dict[str, str]:
"""Get auth headers based on config - supports all auth types."""
handlers = {
AuthType.NONE: lambda: {},
AuthType.API_KEY: self._get_api_key_headers,
AuthType.BEARER: self._get_bearer_headers,
AuthType.COOKIE: self._get_cookie_headers,
# OAuth2 is async and handled separately
}
handler = handlers.get(self.config.auth_type)
return handler() if handler else {}
3. Configuration Over Code
Make behavior configurable, not hardcoded:
# GOOD - Configuration-driven behavior (Pydantic model in config.py)
class ExternalToolConfig(BaseModel):
name: str
transport: TransportType = TransportType.MCP
mcp_transport_mode: McpTransportMode = McpTransportMode.AUTO
auth_type: AuthType = AuthType.NONE
auth_config: dict[str, Any] = Field(default_factory=dict)
# ... other config
MCP Transport Guidelines
FastMCP Auto-Detection
FastMCP can auto-detect transport when given a URL:
/mcpendpoints → typically StreamableHTTP/sseendpoints → typically SSE
But some servers don't follow this convention.
When to Force Transport
from penguiflow.tools.config import ExternalToolConfig, McpTransportMode, TransportType
# SSE endpoints (legacy)
ExternalToolConfig(
name="legacy-server",
transport=TransportType.MCP,
connection="https://server.com/sse",
mcp_transport_mode=McpTransportMode.SSE,
)
# StreamableHTTP endpoints (modern)
ExternalToolConfig(
name="modern-server",
transport=TransportType.MCP,
connection="https://server.com/mcp",
mcp_transport_mode=McpTransportMode.STREAMABLE_HTTP,
)
# Let FastMCP decide (default)
ExternalToolConfig(
name="auto-detect",
transport=TransportType.MCP,
connection="https://server.com/mcp",
mcp_transport_mode=McpTransportMode.AUTO,
)
Checklist Before Implementation
- Does this work for ALL auth types, not just the one I'm testing?
- Does this work for ALL transport types (SSE, StreamableHTTP, STDIO)?
- Is behavior configurable via ExternalToolConfig?
- Are there sensible defaults that don't break existing usage?
- Is error handling comprehensive?
- Does it follow existing patterns in the codebase?
Testing Requirements
When adding new features:
- Test with multiple auth types
- Test with multiple transport types
- Test with edge cases (missing config, invalid values)
- Add unit tests AND integration tests
DNA Pattern References
- See
penguiflow/planner/for ReactPlanner patterns - See
penguiflow/tools/config.pyfor configuration patterns - See
test_generation/*/src/*/external_tools.pyfor usage patterns