smarter-mcp 0.1.4

The highest-level Python framework for building, generating, and running MCP servers.

If Python can call it, Smarter-MCP can serve it.

pip install smarter-mcp

Smarter-MCP sits on top of FastMCP and acts as the orchestration layer that handles everything a developer shouldn't have to think about:

Three ways in, one runtime

1. Existing code — zero rewrites

Point at any module you already have (or anything on PyPI):

import pandas as pd
from smarter_mcp import SmarterMCP

app = SmarterMCP("data-tools")
app.discover_module(pd.DataFrame, include=["describe", "head", "tail"])
app.run()

Or scan an entire local codebase from the CLI:

smarter-mcp serve ./src/mylib

The dual-pass engine (AST + inspect) reads your signatures, builds JSON schemas, and serves them. Nothing to rewrite.

2. Stateful class tools

When your tools need shared state (a DB connection, an API client, an ML model loaded once), @toolkit manages it:

from smarter_mcp import tool, toolkit

@toolkit(lifecycle="session")
class DatabaseClient:
    def __init__(self, host: str = "localhost", port: int = 5432):
        self.conn = connect(host, port)

    @tool(name="run_query")
    def query(self, sql: str) -> list[dict]:
        """Execute a SQL query and return results."""
        return self.conn.execute(sql).fetchall()

One instance per session. Constructor args injected from config. Session instances are evicted via bounded LRU (max 256 entries) with best-effort resource cleanup (close()/__exit__) on eviction. You write the class, Smarter-MCP handles the plumbing.

3. ✍️ Fresh tools from scratch

from smarter_mcp import SmarterMCP, tool, resource

app = SmarterMCP("my-server")

@tool("Greet a user by name")
def greet(name: str) -> str:
    return f"Hello, {name}!"

@resource("config://settings")
def get_settings() -> dict:
    return {"debug": True, "version": "1.0"}

app.run()

⚙️ What the runtime gives every tool

Regardless of how a tool was registered, every call goes through:

• ✅ Schema validation — parameters validated before your function is called. Clean errors back to the agent, not raw tracebacks.
• ✅ Type coercion — agents send "42" instead of 42 constantly. Handled silently.
• ✅ Multimodal — PIL.Image and np.ndarray parameters decoded from ImageContent automatically. Return images and they're wrapped back up.
• ✅ Instance lifecycle — session, singleton, or per-call. Resolved and bound per request.
• ✅ Namespace routing — auto-derived from module paths. No silent name collisions.
• ✅ Auth + rate limiting — API key middleware and sliding-window rate limits, config-driven.

✨ AI-generated tool descriptions

Most Python code in the wild has no docstrings. That's fine.

Point Smarter-MCP at an undocumented library and it will write the tool descriptions for you using Claude, GPT, or any OpenAI-compatible model. Every tool your agent sees gets a clean, accurate description regardless of what the original code looked like.

llm:
  enabled: true
  provider: anthropic        # or openai, openrouter
  model: claude-3-5-haiku-20241022
  cache_path: .smarter-mcp/description-cache.json

or in code:

server = SmarterMCP(
    "my-server",
    llm_enabled=True,
    llm_provider="anthropic",
    llm_model="claude-3-5-haiku-20241022",
)
server.run()

Undocumented code stops being a blocker.

📋 YAML manifest — no Python required

name: my-server
version: 0.1.0

server:
  host: 0.0.0.0
  port: 8000
  transport: sse

sources:
  - path: ./src/my_local_utils
  - module: random
    include: [choices, randint]
    namespace: random_tools

expose:
  include_private: false
  unannotated_policy: warn

smarter-mcp serve --manifest smarter-mcp.yaml

🚀 Getting started

pip install smarter-mcp

For multimodal support (PIL / numpy):

pip install "smarter-mcp[multimodal]"

Then point it at your code:

smarter-mcp serve ./src/mylib --port 8000
smarter-mcp validate ./my_tools.py
smarter-mcp test ./my_tools.py

Built on FastMCP.