Links
Integration type implemented
You.com web search MCP tool as new example in Skybridge's full-stack TypeScript MCP framework
Setup/env vars
YDC_API_KEY: Optional API key for authenticated You.com Search API access
- Without key: Uses keyless operation (100 free searches/day per IP)
- With key: Higher quotas and enhanced features per You.com plan
- Integration is opt-in via MCP tool usage - no behavior changes until explicitly called
- Tool parameters: query (string), count (number 1-20), domains (array), freshness (enum), safeSearch (boolean)
Usage example
// MCP Tool Registration in Skybridge
.registerTool({
name: "youcom-search",
description: "Search the web using You.com for current information",
inputSchema: {
query: z.string().describe("Search query"),
count: z.number().optional().default(10).describe("Number of results"),
domains: z.array(z.string()).optional().describe("Domain filtering"),
freshness: z.enum(["hour", "day", "week", "month", "year"]).optional()
}
}, async ({ query, count = 10, domains, freshness }) => {
const results = await youcomClient.search({ query, count, domains, freshness });
return { structuredContent: results };
});
// Usage in MCP apps
const { useCallTool } = generateHelpers<AppType>();
const searchResults = await callTool("youcom-search", {
query: "TypeScript MCP frameworks 2024",
count: 10,
freshness: "month"
});
// Interactive UI automatically provided via React componentFallback/error behavior
- Missing API key: Uses keyless You.com Search API operation automatically
- Rate limits (429): Clear error suggesting API key upgrade with guidance for higher quotas
- Invalid API key (401): Informative error about checking YDC_API_KEY variable
- Network failures: Graceful error handling with context and retry suggestions
- Service unavailable (5xx): Clear messaging about temporary service issues
- Malformed API responses: Response validation with helpful error messages
- All errors maintain MCP app functionality and provide actionable guidance
Validation performed
✅ TypeScript compilation: All code compiles without errors and follows strict TypeScript patterns
✅ You.com API integration: Both keyless and authenticated operation modes tested and working
✅ MCP tool registration: Tool follows Skybridge's registerTool pattern perfectly
✅ React UI component: Interactive search interface renders and updates correctly
✅ Error scenarios: Comprehensive testing of 401, 429, 5xx, and network failure cases
✅ Search functionality: Query validation, result formatting, and metadata handling verified
✅ Integration patterns: Follows all established Skybridge conventions and architecture
✅ Documentation: Complete README with setup, usage examples, and troubleshooting
✅ Zero breaking changes: Self-contained example with no modifications to existing code
✅ Response validation: Proper handling of malformed or unexpected API responses
✅ Type safety: Full TypeScript support with proper type inference throughout
Implementation highlights
- Complete example application: Self-contained in
examples/youcom-web-search/ directory
- Production-ready: Supports both development (keyless) and production (authenticated) modes
- Rich interactive UI: React component with real-time search, result cards, and loading states
- Comprehensive error handling: Covers all API error scenarios with user-friendly messaging
- Type-safe throughout: Full TypeScript implementation with proper type inference
- Following Skybridge patterns: Uses established
registerTool, view registration, and helper patterns
- Zero dependencies added: Uses existing Skybridge and standard Node.js capabilities
- Educational value: Demonstrates best practices for external API integration in MCP apps
Current status
Implementation complete and PR opened. The integration demonstrates Skybridge's excellent extensibility for external API integrations while providing immediate web search value for any MCP app built with the framework. Documentation includes comprehensive setup guides, usage examples, error handling, and troubleshooting. Awaiting upstream review from the alpic-ai/skybridge team.
Links
Integration type implemented
You.com web search MCP tool as new example in Skybridge's full-stack TypeScript MCP framework
Setup/env vars
YDC_API_KEY: Optional API key for authenticated You.com Search API accessUsage example
Fallback/error behavior
Validation performed
✅ TypeScript compilation: All code compiles without errors and follows strict TypeScript patterns
✅ You.com API integration: Both keyless and authenticated operation modes tested and working
✅ MCP tool registration: Tool follows Skybridge's
registerToolpattern perfectly✅ React UI component: Interactive search interface renders and updates correctly
✅ Error scenarios: Comprehensive testing of 401, 429, 5xx, and network failure cases
✅ Search functionality: Query validation, result formatting, and metadata handling verified
✅ Integration patterns: Follows all established Skybridge conventions and architecture
✅ Documentation: Complete README with setup, usage examples, and troubleshooting
✅ Zero breaking changes: Self-contained example with no modifications to existing code
✅ Response validation: Proper handling of malformed or unexpected API responses
✅ Type safety: Full TypeScript support with proper type inference throughout
Implementation highlights
examples/youcom-web-search/directoryregisterTool, view registration, and helper patternsCurrent status
Implementation complete and PR opened. The integration demonstrates Skybridge's excellent extensibility for external API integrations while providing immediate web search value for any MCP app built with the framework. Documentation includes comprehensive setup guides, usage examples, error handling, and troubleshooting. Awaiting upstream review from the alpic-ai/skybridge team.