Smithery Openapi Server

🚀 Smithery Registry OpenAPI Server

This server provides an OpenAPI interface for the Smithery Registry API, allowing you to search for and obtain the startup configuration of Model Context Protocol (MCP) servers.

🚀 Quick Start

This server offers an OpenAPI interface for the Smithery Registry API, enabling you to search for and retrieve the startup configuration of Model Context Protocol (MCP) servers.

✨ Features

• List available MCP servers with advanced filtering capabilities.
• Retrieve detailed information about a specific server, including connection configuration.
• Generate a WebSocket URL containing base64-encoded configuration.
• Authenticate via bearer token.
• Be compatible with OpenAPI tools and clients.

🔐 Authentication

All requests to the Smithery Registry API require authentication:

• You need to provide a bearer token in the Authorization header.
• Format: Authorization: Bearer your-api-token
• Obtain the token from the API keys section of your Smithery user profile.

📦 Installation

pip install -r requirements.txt

💻 Usage Examples

Basic Usage

Run the server:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Advanced Usage

API Endpoints

1. GET /servers - List available MCP servers

   • Query parameters:
     • q: Search query (semantic search)
     • page: Page number (default: 1)
     • pageSize: Number of items per page (default: 10)
   • Use advanced filtering syntax in the q parameter:
     • Text search: "machine learning"
     • Owner filtering: owner:username
     • Repository filtering: repo:repository-name
     • Deployment status: is:deployed
     • Example: "owner:smithery-ai repo:fetch is:deployed machine learning"

2. GET /servers/{qualified_name} - Get detailed information about a specific server

3. POST /create-websocket-url - Create a WebSocket URL containing encoded configuration

   • Request body:

     {
       "qualifiedName": "username/repository",
       "config": {
         // Configuration object conforming to the server's schema
       }
     }
     

WebSocket Connection

Directly connect to the WebSocket of an MCP server:

• URL format: https://server.smithery.ai/${qualifiedName}/ws?config=${base64encode(config)}
• The configuration must conform to the server's configSchema.
• The configuration is base64-encoded JSON.

Integration with OpenAPI Tools

This server is designed to be compatible with any OpenAPI-compatible tools and frameworks. The API follows RESTful conventions and provides detailed OpenAPI documentation at runtime. Access the /docs endpoint.

Using the TypeScript SDK

For use with the Smithery TypeScript SDK:

import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js"
import { createSmitheryUrl } from "@smithery/sdk/config.js"

const url = createSmitheryUrl(
  "https://your-smithery-mcp-server/ws",
  {
    // Configuration object conforms to the schema
  },
)
const transport = new WebSocketClientTransport(url)

📄 License

MIT