{"passport":{"unfragile":{"@version":"1.0","version":"2026-05","artifact":{"id":"awesome-ref","slug":"ref","name":"Ref","type":"mcp","url":"https://github.com/ref-tools/ref-tools-mcp","page_url":"https://unfragile.ai/ref","categories":["mcp-servers"],"tags":[],"pricing":{"model":"open_source","free":true,"starting_price":null},"status":"active","verified":false},"capabilities":[{"id":"awesome-ref__cap_0","uri":"capability://search.retrieval.token.efficient.semantic.documentation.search.with.context.filtering","name":"token-efficient semantic documentation search with context filtering","description":"Performs semantic search across 1000+ public repositories and documentation sites through the Ref API, returning intelligently filtered results that minimize irrelevant context. The system tracks session-based search trajectories to avoid redundant queries and implements result ranking to surface the most relevant documentation snippets, reducing token consumption compared to unfiltered full-document retrieval.","intents":["Find relevant API documentation for a library without loading entire docs into context","Search across multiple framework versions to find the right API signature","Quickly locate code examples from popular open-source projects","Reduce LLM context window usage when researching unfamiliar libraries"],"best_for":["AI coding agents and LLM-powered IDEs needing lightweight documentation access","Teams building agentic systems with strict token budgets","Developers working with unfamiliar or rapidly-evolving libraries"],"limitations":["Search results limited to indexed public repositories and documentation sites — private/internal docs require separate indexing","Search quality depends on Ref API's indexing freshness; real-time documentation updates may lag","Session-based trajectory tracking only persists within HTTP transport mode, not stdio mode","No full-text search fallback if semantic search returns insufficient results"],"requires":["REF_API_KEY or REF_ALPHA environment variable for authentication","Network connectivity to Ref API service (api.ref.tools or equivalent)","MCP client compatible with tool calling (OpenAI, Anthropic, or standard MCP clients)"],"input_types":["text query string (library name, function name, concept)","optional context parameters (language, framework, version)"],"output_types":["JSON with DeepResearchShape format for OpenAI clients (structured with title, content, source URL)","Plain text markdown for standard MCP clients"],"categories":["search-retrieval","memory-knowledge"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-ref__cap_1","uri":"capability://search.retrieval.url.based.documentation.content.extraction.with.client.aware.formatting","name":"url-based documentation content extraction with client-aware formatting","description":"Fetches and extracts content from specific documentation URLs through the Ref API, returning formatted content optimized for the detected client type. Implements client detection logic (index.ts 23-37, 394-422) to return DeepResearchShape JSON for OpenAI clients or plain text for standard MCP clients, enabling seamless integration across different AI agent architectures.","intents":["Retrieve full content from a specific documentation page URL","Extract code examples from a known documentation link","Read the complete API reference for a specific function or class","Access documentation in the format expected by the AI client being used"],"best_for":["AI agents that have identified a specific documentation URL and need full content","Multi-client deployments serving both OpenAI and standard MCP clients","Workflows combining search results with targeted deep-dives into specific pages"],"limitations":["Requires valid, accessible URL — will fail on private/authenticated documentation pages","Content extraction quality depends on Ref API's HTML parsing; complex layouts may not extract cleanly","No caching of fetched content — repeated requests to same URL incur API calls","Client detection relies on User-Agent or explicit client type hints; misdetection results in wrong response format"],"requires":["REF_API_KEY or REF_ALPHA environment variable","Valid, publicly-accessible documentation URL","Network connectivity to Ref API service"],"input_types":["URL string (http/https)","optional client type hint for format selection"],"output_types":["DeepResearchShape JSON object (title, content, source URL) for OpenAI clients","Plain text markdown for standard MCP clients"],"categories":["search-retrieval","tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-ref__cap_2","uri":"capability://tool.use.integration.multi.transport.mcp.server.deployment.with.stateful.http.sessions","name":"multi-transport mcp server deployment with stateful http sessions","description":"Deploys as an MCP server supporting both stdio (local npm package) and HTTP (remote service) transports, with HTTP transport implementing session management through transports and sessionClientInfo objects (index.ts 376-536, 537-544). Enables stateful interactions across multiple requests in HTTP mode while maintaining compatibility with local stdio execution, allowing the same codebase to serve both embedded and remote deployment scenarios.","intents":["Deploy ref-tools as a local npm package in an existing MCP client setup","Run ref-tools as a remote HTTP service accessible to multiple AI agents","Maintain search context and session state across multiple agent requests","Switch deployment mode via environment variable without code changes"],"best_for":["Teams deploying MCP servers across multiple environments (local, cloud, containerized)","Multi-tenant scenarios requiring per-client session isolation","Development workflows needing both local testing and remote deployment"],"limitations":["Session state only persists in HTTP transport mode; stdio mode is stateless","HTTP transport adds network latency (~50-200ms per request) compared to stdio","Session management requires external state store for production deployments; in-memory storage lost on server restart","TRANSPORT_TYPE environment variable must be set correctly; no auto-detection of optimal transport"],"requires":["Node.js 18+ for TypeScript execution","TRANSPORT_TYPE environment variable set to 'stdio' or 'http'","Port 8080 available if using HTTP transport","REF_API_KEY or REF_ALPHA for API authentication"],"input_types":["MCP tool call requests (CallToolRequestSchema)","HTTP POST requests with JSON payload (for HTTP transport)"],"output_types":["MCP tool response messages","HTTP JSON responses with session identifiers"],"categories":["tool-use-integration","automation-workflow"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-ref__cap_3","uri":"capability://tool.use.integration.priority.based.api.authentication.with.runtime.configuration.override","name":"priority-based api authentication with runtime configuration override","description":"Implements a three-tier authentication resolution system (getAuthHeaders function, index.ts 221-242) that prioritizes runtime configuration over environment variables, enabling dynamic API key switching without server restart. Supports both standard REF_API_KEY and early-access REF_ALPHA authentication paths, constructing appropriate X-Ref-Api-Key or X-Ref-Alpha headers and including session identifiers for HTTP transport requests.","intents":["Authenticate with Ref API using environment variables for standard deployments","Override API key at runtime for multi-tenant scenarios","Use alpha/early-access features via REF_ALPHA token","Include session context in API requests for stateful interactions"],"best_for":["Multi-tenant deployments requiring per-request API key configuration","Development workflows testing multiple API keys without restarting server","Alpha/beta feature access for early adopters"],"limitations":["Runtime API key override only works in HTTP transport mode; stdio mode uses environment variables only","No API key validation before sending requests; invalid keys fail at Ref API level","Session identifiers only included for HTTP transport; stdio requests lack session context","No built-in rate limiting or quota management; relies on Ref API for enforcement"],"requires":["REF_API_KEY environment variable OR currentApiKey in HTTP config parameters","Optional REF_ALPHA environment variable for early-access features","Valid API key format expected by Ref API service"],"input_types":["Environment variables (REF_API_KEY, REF_ALPHA)","HTTP config parameters (currentApiKey for runtime override)"],"output_types":["HTTP headers (X-Ref-Api-Key or X-Ref-Alpha)","Session identifiers included in API requests"],"categories":["tool-use-integration","safety-moderation"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-ref__cap_4","uri":"capability://tool.use.integration.client.type.detection.and.response.format.adaptation","name":"client-type detection and response format adaptation","description":"Dynamically detects client type through multiple mechanisms (User-Agent headers, explicit hints, client registry) and adapts tool response formats accordingly. OpenAI clients receive DeepResearchShape JSON objects with structured title/content/source fields, while standard MCP clients receive plain text markdown, enabling seamless integration across heterogeneous AI agent architectures without requiring client-specific configuration.","intents":["Serve OpenAI clients with structured JSON responses optimized for their API","Serve standard MCP clients with plain text responses","Support multiple client types from a single MCP server instance","Automatically format responses without explicit client configuration"],"best_for":["Multi-client deployments serving both OpenAI and standard MCP clients","Organizations with heterogeneous AI agent infrastructure","MCP servers needing to support multiple response formats transparently"],"limitations":["Client detection relies on heuristics (User-Agent, headers); misdetection results in wrong response format","No explicit client type parameter; detection is implicit and may fail for custom/unknown clients","Response format adaptation happens at tool level; some clients may expect different formats for different tools","DeepResearchShape format is OpenAI-specific; other structured formats not supported"],"requires":["Client must send identifiable User-Agent header or client type hint","MCP server must be configured with client detection logic (built-in via createServerInstance)"],"input_types":["HTTP headers (User-Agent, custom client type hints)","MCP tool call requests with implicit client context"],"output_types":["DeepResearchShape JSON for OpenAI clients","Plain text markdown for standard MCP clients"],"categories":["tool-use-integration","automation-workflow"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-ref__cap_5","uri":"capability://memory.knowledge.context.aware.documentation.search.with.session.trajectory.tracking","name":"context-aware documentation search with session trajectory tracking","description":"Tracks search history and query patterns within HTTP sessions to avoid redundant searches and inform result ranking. The session-based trajectory system (index.ts 537-544) maintains per-client search context, enabling the system to understand search intent progression and filter results based on previous queries, reducing token waste from repeated documentation lookups and improving result relevance over multiple agent interactions.","intents":["Avoid returning duplicate documentation results across multiple agent queries","Understand search intent progression to improve result ranking","Maintain search context across multiple agent interactions","Reduce token consumption by filtering redundant results based on session history"],"best_for":["Long-running agent sessions with multiple documentation queries","Multi-turn conversations where search context matters","Token-constrained deployments needing to minimize redundant results"],"limitations":["Session trajectory tracking only available in HTTP transport mode; stdio mode has no session context","Session state is in-memory; lost on server restart without external persistence","No configurable session timeout; sessions persist for server lifetime","Trajectory tracking adds ~50-100ms overhead per search due to history lookup and filtering"],"requires":["HTTP transport mode (TRANSPORT_TYPE=http)","Stateful client maintaining session identifiers across requests","Multiple queries within same session to benefit from trajectory tracking"],"input_types":["Search query string","Session identifier (implicit in HTTP transport)"],"output_types":["Filtered search results with trajectory-aware ranking","Session context metadata"],"categories":["memory-knowledge","planning-reasoning"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-ref__cap_6","uri":"capability://automation.workflow.npm.package.and.docker.deployment.with.environment.based.configuration","name":"npm package and docker deployment with environment-based configuration","description":"Provides multiple deployment methods (npm package, Docker container, HTTP server, Smithery platform) with unified environment-variable-based configuration. Supports TRANSPORT_TYPE selection, API key configuration via REF_API_KEY/REF_ALPHA, and HTTP port customization, enabling flexible deployment across development, staging, and production environments without code changes.","intents":["Deploy ref-tools as a local npm package in existing MCP setups","Containerize ref-tools for cloud/Kubernetes deployments","Run ref-tools as a standalone HTTP service","Deploy to Smithery platform for managed MCP hosting"],"best_for":["Teams with diverse deployment infrastructure (local, Docker, cloud)","Organizations needing consistent configuration across environments","Developers wanting quick deployment without infrastructure setup"],"limitations":["Docker deployment requires building image; no pre-built images provided in repo","Environment variable configuration is flat; no hierarchical config file support","HTTP server deployment requires manual port management and reverse proxy setup","Smithery deployment requires account and platform-specific configuration"],"requires":["Node.js 18+ for npm package deployment","Docker 20.10+ for Docker deployment","Port 8080 available for HTTP server deployment","Smithery account for Smithery platform deployment"],"input_types":["Environment variables (TRANSPORT_TYPE, REF_API_KEY, REF_ALPHA, HTTP port)","Docker build arguments","Smithery platform configuration"],"output_types":["Running MCP server (stdio or HTTP)","Docker container with MCP server","HTTP service on configured port"],"categories":["automation-workflow","tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-ref__cap_7","uri":"capability://tool.use.integration.mcp.tool.schema.definition.with.client.specific.tool.naming","name":"mcp tool schema definition with client-specific tool naming","description":"Defines two core MCP tools (search_documentation and read_url) with client-specific naming conventions and schema validation. The tool definitions include input schemas with required/optional parameters, output descriptions, and client-specific naming adaptations (e.g., different tool names for OpenAI vs standard MCP clients), enabling proper tool discovery and invocation across heterogeneous MCP clients.","intents":["Define searchable MCP tools with proper schema validation","Support client-specific tool naming conventions","Enable proper tool discovery in MCP clients","Validate tool inputs before passing to Ref API"],"best_for":["MCP client implementations needing tool schema discovery","Teams building custom MCP clients with specific tool naming requirements","Developers integrating ref-tools into existing MCP ecosystems"],"limitations":["Tool schemas are hardcoded; no dynamic schema generation based on Ref API capabilities","Client-specific naming requires explicit detection; no fallback for unknown clients","Schema validation is basic; complex input validation delegated to Ref API","No tool versioning; schema changes require server restart"],"requires":["MCP client compatible with tool calling","Tool schema definitions in MCP server (built-in via index.ts 65-93)"],"input_types":["Tool call requests with parameters matching defined schemas","Query strings, URLs, optional context parameters"],"output_types":["Tool response messages with structured content","Error messages for invalid inputs"],"categories":["tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0}],"trust":{"score":29,"verified":false,"data_access_risk":"high","permissions":["REF_API_KEY or REF_ALPHA environment variable for authentication","Network connectivity to Ref API service (api.ref.tools or equivalent)","MCP client compatible with tool calling (OpenAI, Anthropic, or standard MCP clients)","REF_API_KEY or REF_ALPHA environment variable","Valid, publicly-accessible documentation URL","Network connectivity to Ref API service","Node.js 18+ for TypeScript execution","TRANSPORT_TYPE environment variable set to 'stdio' or 'http'","Port 8080 available if using HTTP transport","REF_API_KEY or REF_ALPHA for API authentication"],"failure_modes":["Search results limited to indexed public repositories and documentation sites — private/internal docs require separate indexing","Search quality depends on Ref API's indexing freshness; real-time documentation updates may lag","Session-based trajectory tracking only persists within HTTP transport mode, not stdio mode","No full-text search fallback if semantic search returns insufficient results","Requires valid, accessible URL — will fail on private/authenticated documentation pages","Content extraction quality depends on Ref API's HTML parsing; complex layouts may not extract cleanly","No caching of fetched content — repeated requests to same URL incur API calls","Client detection relies on User-Agent or explicit client type hints; misdetection results in wrong response format","Session state only persists in HTTP transport mode; stdio mode is stateless","HTTP transport adds network latency (~50-200ms per request) compared to stdio","builder identity is not verified yet","no observed match outcomes yet"],"rank_breakdown":{"adoption":0.05,"quality":0.41,"ecosystem":0.39999999999999997,"match_graph":0.25,"freshness":0.52,"weights":{"adoption":0.25,"quality":0.25,"ecosystem":0.15,"match_graph":0.23,"freshness":0.12}},"observed_outcomes":{"matches":0,"success_rate":0,"avg_confidence":0,"top_intents":[],"last_matched_at":null},"maintenance":{"status":"active","updated_at":"2026-06-17T09:51:04.048Z","last_scraped_at":"2026-05-03T14:00:15.503Z","last_commit":null},"community":{"stars":null,"forks":null,"weekly_downloads":null,"model_downloads":null,"model_likes":null}},"distribution":{"claim_url":"https://unfragile.ai/submit?claim=ref","compare_url":"https://unfragile.ai/compare?artifact=ref"}},"signature":"CKgEHvG10B8LMl/lcVw2HN6ecn6Yc+6EziRywJMsb05UUnrl25SIcKFQkxEoL6yLf1sRrmcu1Cg2ATo7Xn4pCw==","signedAt":"2026-06-20T19:52:58.055Z","signedBy":"unfragile.ai","version":1},"_links":{"self":"https://unfragile.ai/api/v1/passport/ref","artifact":"https://unfragile.ai/ref","verify":"https://unfragile.ai/api/v1/verify?slug=ref","publicKey":"https://unfragile.ai/api/v1/trust-passport-public-key","spec":"https://unfragile.ai/trust","schema":"https://unfragile.ai/schema.json","docs":"https://unfragile.ai/docs"}}