toolregistry-server

Define custom tools and serve them via OpenAPI or MCP interfaces. Built on ToolRegistry.

Overview

toolregistry-server lets you register Python functions as tools and expose them as services through multiple protocols. It provides:

• Central Route Table: A unified routing layer that bridges ToolRegistry and protocol adapters
• OpenAPI Adapter: Expose tools as RESTful HTTP endpoints with automatic OpenAPI schema generation
• MCP Adapter: Expose tools via the Model Context Protocol for LLM integration
• Authentication: Built-in Bearer token authentication support
• CLI: Command-line interface for running servers

Ecosystem

The ToolRegistry ecosystem consists of three packages:

Package	Description	Repository
toolregistry	Core library - Tool model, ToolRegistry, client integration	Oaklight/ToolRegistry
toolregistry-server	Tool server - define tools and serve via OpenAPI/MCP	Oaklight/toolregistry-server
toolregistry-hub	Tool collection - Built-in tools, default server configuration	Oaklight/toolregistry-hub

toolregistry (core)
       ↓
toolregistry-server (tool server)
       ↓
toolregistry-hub (tool collection + server config)

Installation

Basic Installation

pip install toolregistry-server

With OpenAPI Support

pip install toolregistry-server[openapi]

With MCP Support

pip install toolregistry-server[mcp]

Full Installation

pip install toolregistry-server[all]

Quick Start

Using RouteTable

from toolregistry import ToolRegistry
from toolregistry_server import RouteTable

# Create a registry and register tools
registry = ToolRegistry()

@registry.register
def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

# Create a route table
route_table = RouteTable(registry)

# List all routes
for route in route_table.list_routes():
    print(f"{route.path} -> {route.tool_name}")

Creating an OpenAPI Server

from toolregistry import ToolRegistry
from toolregistry_server import RouteTable
from toolregistry_server.openapi import create_openapi_app

# Setup registry and route table
registry = ToolRegistry()
# ... register tools ...
route_table = RouteTable(registry)

# Create FastAPI app
app = create_openapi_app(route_table)

# Run with uvicorn
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Creating an MCP Server

from toolregistry import ToolRegistry
from toolregistry_server import RouteTable
from toolregistry_server.mcp import create_mcp_server

# Setup registry and route table
registry = ToolRegistry()
# ... register tools ...
route_table = RouteTable(registry)

# Create MCP server
server = create_mcp_server(route_table)

# Run the server
if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

Using the CLI

# Start OpenAPI server
toolregistry-server --mode openapi --port 8000

# Start MCP server (stdio)
toolregistry-server --mode mcp

# With authentication
toolregistry-server --mode openapi --auth-token "your-secret-token"

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      ToolRegistry                           │
│                   (tool definitions)                        │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                       RouteTable                            │
│              (central routing layer)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ RouteEntry  │  │ RouteEntry  │  │ RouteEntry  │  ...    │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ OpenAPI Adapter │ │   MCP Adapter   │ │  gRPC Adapter   │
│   (FastAPI)     │ │   (MCP SDK)     │ │    (future)     │
└─────────────────┘ └─────────────────┘ └─────────────────┘
          │               │               │
          ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  HTTP Clients   │ │   MCP Clients   │ │  gRPC Clients   │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Documentation

• Full Documentation
• API Reference
• Examples

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• ToolRegistry - Core library
• toolregistry-hub - Built-in tool collection
• Model Context Protocol - MCP specification