smf-mcp 0.1.26

Enterprise-grade MCP framework built on FastMCP

SMF - Enterprise MCP Framework

SMF is a production-ready Python framework built on top of FastMCP that makes it significantly simpler to create, structure, and deploy MCP (Model Context Protocol) servers.

Features

• 🏗️ High-level abstractions: ServerFactory and AppBuilder for minimal boilerplate
• 🔧 Tool registration: Simple decorator-based tool registration
• 🔌 Plugin system: Extensible architecture with stable interfaces
• 🚀 CLI & Templates: Project scaffolding and code generation
• 📦 Simple & Focused: Tools-only approach, no unnecessary complexity

Architecture

┌─────────────────────────────┐
│   CLI & Templates           │
├─────────────────────────────┤
│  Extensions & Plugins       │
├─────────────────────────────┤
│    Core SMF Layer          │
├─────────────────────────────┤
│    FastMCP (Upstream)        │
└─────────────────────────────┘

SMF wraps FastMCP without modifying it, ensuring compatibility with FastMCP updates while adding enterprise features.

Quick Start

Installation

uv add smf-mcp
# or
pip install smf-mcp

Simple Server

from smf import create_server

# Create server
mcp = create_server("My Server")

# Register a tool
@mcp.tool
def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    from smf.transport import run_server
    run_server(mcp)

Advanced Server with AppBuilder

from smf import AppBuilder

# Use AppBuilder for fluent registration
with AppBuilder() as builder:
    @builder.tool(tags=["math"])
    def add(a: float, b: float) -> float:
        """Add two numbers."""
        return a + b

    mcp = builder.build()

if __name__ == "__main__":
    from smf.transport import run_server
    run_server(mcp, transport="http", port=8000)

CLI

# Initialize new project
smf init my-server

# Initialize project with Elasticsearch plugin
smf init my-server --elasticsearch --es-index "products"

# Run server
smf run server.py --transport http --port 8000

# Inspect server (Official Web Inspector)
smf inspector server.py

Core Components

ServerFactory

Creates configured FastMCP servers:

from smf import ServerFactory

factory = ServerFactory()
mcp = factory.create(name="My Server")

AppBuilder

Fluent interface for registering tools:

from smf import AppBuilder

builder = AppBuilder()
builder.tool(my_function)
mcp = builder.build()

Transport

Run servers with different transport mechanisms:

from smf.transport import run_server

# Stdio (default)
run_server(mcp)

# HTTP
run_server(mcp, transport="http", host="0.0.0.0", port=8000)

# SSE
run_server(mcp, transport="sse", host="0.0.0.0", port=8000)

Authentication

SMF relies on FastMCP's auth system and adds a generic OIDC/OAuth proxy provider that can be configured entirely via environment variables.

Enable auth (no code changes):

FASTMCP_SERVER_AUTH=smf.auth.providers.oidc.OIDCProxyProvider
FASTMCP_SERVER_AUTH_OIDC_CONFIG_URL=https://idp.example.com/.well-known/openid-configuration
FASTMCP_SERVER_AUTH_OIDC_CLIENT_ID=your-client-id
FASTMCP_SERVER_AUTH_OIDC_CLIENT_SECRET=your-client-secret
FASTMCP_SERVER_AUTH_OIDC_BASE_URL=https://your-mcp-server.example.com

If your IdP does not support OIDC discovery, you can provide explicit endpoints:

FASTMCP_SERVER_AUTH_OIDC_AUTHORIZATION_ENDPOINT=https://idp.example.com/oauth2/authorize
FASTMCP_SERVER_AUTH_OIDC_TOKEN_ENDPOINT=https://idp.example.com/oauth2/token
FASTMCP_SERVER_AUTH_OIDC_JWKS_URI=https://idp.example.com/.well-known/jwks.json
FASTMCP_SERVER_AUTH_OIDC_ISSUER=https://idp.example.com

Optional authorization helper for tools:

from smf.auth import require_scopes

@mcp.tool
@require_scopes("read:data")
def read_data() -> str:
    return "ok"

Plugins

Elasticsearch Plugin

Create Elasticsearch-powered MCP servers:

# Create server with CLI
smf init my-server --elasticsearch --es-index "products"

# Or use in code
from smf.plugins.elasticsearch import (
    ElasticsearchConfiguration,
    build_elasticsearch_connection,
    create_elasticsearch_tools,
)

es_config = ElasticsearchConfiguration.from_env()
es_client = build_elasticsearch_connection(es_config)  # Returns native Elasticsearch client
mcp = create_server("My Server")
tools = create_elasticsearch_tools(es_client, index="products")
for tool in tools:
    mcp.tool(tool)

Install: Choose the version matching your Elasticsearch cluster:

• pip install smf-mcp[elasticsearch7] or uv add smf-mcp[elasticsearch7] for Elasticsearch 7.x
• pip install smf-mcp[elasticsearch8] or uv add smf-mcp[elasticsearch8] for Elasticsearch 8.x
• pip install smf-mcp[elasticsearch9] or uv add smf-mcp[elasticsearch9] for Elasticsearch 9.x

Project Structure

When you initialize a new project with smf init, you get:

my-server/
├── src/
│   └── tools/
│       ├── __init__.py
│       └── tools.py          # Your tools
├── server.py                  # Main server file
└── README.md                  # Project documentation

Requirements

• Python 3.11+
• FastMCP >= 2.11

License

MIT

Credits

Built on FastMCP by Prefect.