restmcp 0.1.0__py3-none-any.whl

pythia/__init__.py

@@ -0,0 +1,22 @@
+from pythia.datasource import DataSource
+from pythia.entity import Entity
+from pythia.repository import Repository
+from pythia.service import Service
+from pythia.endpoint import Endpoint
+from pythia.server import Server
+from pythia.logging import Logger
+from pythia.exceptions import ValidationError, NotFoundError
+from pythia.types import McpDefinition
+
+__all__ = [
+    "DataSource",
+    "Entity",
+    "Repository",
+    "Service",
+    "Endpoint",
+    "Server",
+    "Logger",
+    "ValidationError",
+    "NotFoundError",
+    "McpDefinition",
+]

pythia/cli/__init__.py

@@ -0,0 +1,11 @@
+import click
+from pythia.cli.new import new_command
+
+
+@click.group()
+def app():
+    """pythia — framework for building MCP servers."""
+    pass
+
+
+app.add_command(new_command, name="new")

pythia/cli/new.py

@@ -0,0 +1,65 @@
+import os
+import click
+
+TEMPLATE_DIRS = ["datasource", "models", "repositories", "services", "tools", "urls"]
+
+MAIN_PY = """\
+from pythia import Server
+import urls  # auto-discovery
+
+server = Server.get_instance()
+
+if __name__ == "__main__":
+    server.start()
+"""
+
+URLS_INIT = """\
+import importlib
+import pkgutil
+
+for _info in pkgutil.iter_modules(__path__):
+    importlib.import_module(f"{__name__}.{_info.name}")
+"""
+
+PYPROJECT = """\
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{name}"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "pythia",
+]
+"""
+
+
+@click.command()
+@click.argument("name")
+def new_command(name: str):
+    """Create a new MCP server with the pythia structure."""
+    base = os.path.join(os.getcwd(), name)
+
+    if os.path.exists(base):
+        click.echo(f"Error: directory '{name}' already exists.", err=True)
+        raise SystemExit(1)
+
+    os.makedirs(base)
+
+    for d in TEMPLATE_DIRS:
+        os.makedirs(os.path.join(base, d))
+        open(os.path.join(base, d, "__init__.py"), "w").close()
+
+    with open(os.path.join(base, "urls", "__init__.py"), "w") as f:
+        f.write(URLS_INIT)
+
+    with open(os.path.join(base, "main.py"), "w") as f:
+        f.write(MAIN_PY)
+
+    with open(os.path.join(base, "pyproject.toml"), "w") as f:
+        f.write(PYPROJECT.format(name=name))
+
+    click.echo(f"Project '{name}' created successfully.")
+    click.echo(f"  cd {name} && pip install -e . && python main.py")

pythia/datasource.py

@@ -0,0 +1,18 @@
+from abc import ABC
+
+
+class DataSource(ABC):
+    """External data provider (HTTP, DB, file). Subclass names must end with 'DataSource'."""
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if not cls.__name__.endswith("DataSource"):
+            raise TypeError(
+                f"DataSource subclasses must end with 'DataSource' "
+                f"(got: '{cls.__name__}'). Rename to '{cls.__name__}DataSource'."
+            )
+
+    def __new__(cls, *args, **kwargs):
+        if cls is DataSource:
+            raise TypeError("DataSource is abstract and cannot be instantiated directly.")
+        return super().__new__(cls)

pythia/endpoint.py

@@ -0,0 +1,140 @@
+import asyncio
+import inspect
+from abc import ABC
+
+from fastapi import Depends, Request
+from fastapi.responses import JSONResponse
+
+from pythia.exceptions import PythiaException, ValidationError
+
+
+def _validate_mcp_definition(cls_name: str, mcp_def: object) -> None:
+    if not isinstance(mcp_def, dict):
+        raise TypeError(
+            f"{cls_name}: mcp_definition must be a dict, got {type(mcp_def).__name__}"
+        )
+    for key in ("name", "description"):
+        val = mcp_def.get(key)
+        if not isinstance(val, str) or not val.strip():
+            raise TypeError(
+                f"{cls_name}: mcp_definition['{key}'] must be a non-empty string"
+            )
+    params = mcp_def.get("parameters")
+    if params is not None:
+        if not isinstance(params, dict):
+            raise TypeError(
+                f"{cls_name}: mcp_definition['parameters'] must be a dict"
+            )
+        props = params.get("properties")
+        if props is not None and not isinstance(props, dict):
+            raise TypeError(
+                f"{cls_name}: mcp_definition['parameters']['properties'] must be a dict"
+            )
+
+
+class Endpoint(ABC):
+    """HTTP + MCP endpoint. Subclasses auto-register on class definition when url, method, mcp_definition, and callback are all set."""
+
+    disabled: bool = False
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if not cls.__name__.endswith("Endpoint"):
+            raise TypeError(
+                f"Endpoint subclasses must end with 'Endpoint' "
+                f"(got: '{cls.__name__}'). Rename to '{cls.__name__}Endpoint'."
+            )
+
+        if getattr(cls, "disabled", False):
+            return
+
+        _required = ("url", "method", "mcp_definition", "callback")
+        if all(vars(cls).get(attr) for attr in _required):
+            _validate_mcp_definition(cls.__name__, vars(cls)["mcp_definition"])
+            try:
+                cls()
+            except TypeError as e:
+                raise TypeError(
+                    f"{cls.__name__}: auto-registration failed. "
+                    f"Endpoint subclasses must not define __init__ with parameters — "
+                    f"use Service/Repository for dependencies. Original error: {e}"
+                ) from e
+
+    async def _callback(self, request: Request):
+        try:
+            try:
+                data = await request.json()
+            except Exception:
+                data = {}
+            data = data or {}
+
+            valid_params = self.mcp_definition.get("parameters", {}).get("properties", {})
+            parameters = {}
+
+            for key, value in data.items():
+                if key not in valid_params:
+                    raise ValidationError(f"Invalid parameter: {key}")
+                parameters[key] = value
+
+            if inspect.iscoroutinefunction(self.callback):
+                result = await self.callback(**parameters)
+            else:
+                loop = asyncio.get_running_loop()
+                result = await loop.run_in_executor(
+                    None, lambda: self.callback(**parameters)
+                )
+
+            return JSONResponse({
+                "tool": self.mcp_definition["name"],
+                "result": result,
+                "success": True,
+            })
+
+        except PythiaException as e:
+            return JSONResponse({
+                "error": e.message,
+                "tool": self.mcp_definition["name"],
+                "success": False,
+                "error_type": e.__class__.__name__,
+            }, status_code=e.status_code)
+
+        except Exception as e:
+            return JSONResponse({
+                "error": str(e),
+                "tool": self.mcp_definition["name"],
+                "success": False,
+                "error_type": "InternalServerError",
+            }, status_code=500)
+
+    def __init__(self):
+        from pythia.server import Server
+        from pythia.rest import _auth_dependency
+
+        self.mcp_definition = getattr(self, "mcp_definition", None)
+        if not self.mcp_definition:
+            raise ValueError(f"{self.__class__.__name__}: mcp_definition is required")
+
+        self.method = getattr(self, "method", None)
+        if not self.method:
+            raise ValueError(f"{self.__class__.__name__}: method is required")
+
+        self.url = getattr(self, "url", None)
+        if not self.url:
+            raise ValueError(f"{self.__class__.__name__}: url is required")
+
+        if not getattr(self, "callback", None):
+            raise ValueError(f"{self.__class__.__name__}: callback is required")
+
+        endpoint_self = self
+
+        async def route_handler(request: Request):
+            return await endpoint_self._callback(request)
+
+        server = Server.get_instance()
+        server.app.add_api_route(
+            self.url,
+            route_handler,
+            methods=[self.method],
+            dependencies=[Depends(_auth_dependency)],
+        )
+        server.register_url_handler(self)

pythia/entity.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+
+class Entity(BaseModel):
+    """Pydantic model for data returned by a DataSource. Subclass names must end with 'Entity'."""
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if not cls.__name__.endswith("Entity"):
+            raise TypeError(
+                f"Entity subclasses must end with 'Entity' "
+                f"(got: '{cls.__name__}'). Rename to '{cls.__name__}Entity'."
+            )

pythia/exceptions.py

@@ -0,0 +1,17 @@
+class PythiaException(Exception):
+    """Base exception for pythia. Carries an HTTP status code alongside the message."""
+
+    def __init__(self, message: str, status_code: int = 500):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class ValidationError(PythiaException):
+    def __init__(self, message: str):
+        super().__init__(message, status_code=400)
+
+
+class NotFoundError(PythiaException):
+    def __init__(self, message: str):
+        super().__init__(message, status_code=404)

pythia/logging.py

@@ -0,0 +1,35 @@
+import logging
+import os
+
+
+class Logger:
+    """Thin wrapper over Python's logging module. Log level configurable via LOG_LEVEL env var (default: INFO)."""
+
+    def __init__(self, name: str):
+        level_name = os.getenv("LOG_LEVEL", "INFO").upper()
+        level = getattr(logging, level_name, logging.INFO)
+
+        self._logger = logging.getLogger(name)
+        self._logger.setLevel(level)
+
+        if not self._logger.handlers:
+            handler = logging.StreamHandler()
+            handler.setLevel(level)
+            formatter = logging.Formatter(
+                "[%(asctime)s] %(levelname)s %(name)s — %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+            handler.setFormatter(formatter)
+            self._logger.addHandler(handler)
+
+    def info(self, msg: str, *args, **kwargs):
+        self._logger.info(msg, *args, **kwargs)
+
+    def warning(self, msg: str, *args, **kwargs):
+        self._logger.warning(msg, *args, **kwargs)
+
+    def error(self, msg: str, *args, **kwargs):
+        self._logger.error(msg, *args, **kwargs)
+
+    def debug(self, msg: str, *args, **kwargs):
+        self._logger.debug(msg, *args, **kwargs)

pythia/mcp.py

@@ -0,0 +1,66 @@
+from typing import Any, Dict, List, Optional
+
+
+_JSON_TO_PYTHON = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+    "object": dict,
+}
+
+
+class McpApp:
+    """Builds a FastMCP instance from registered url_handlers, mapping mcp_definition to typed pydantic tool wrappers."""
+
+    def build(self, url_handlers: List[Any]):
+        from fastmcp import FastMCP
+
+        mcp = FastMCP("pythia")
+        for handler in url_handlers:
+            self._register_tool(mcp, handler)
+        return mcp
+
+    def _register_tool(self, mcp: Any, handler: Any):
+        from pydantic import Field, create_model
+        import inspect
+
+        def_dict = handler.mcp_definition
+        name = def_dict["name"]
+        description = def_dict["description"]
+        properties = def_dict.get("parameters", {}).get("properties", {})
+
+        pydantic_fields = {}
+        for prop_name, prop_data in properties.items():
+            ptype = prop_data.get("type")
+            if ptype == "array":
+                item_ptype = prop_data.get("items", {}).get("type", "string")
+                item_type = _JSON_TO_PYTHON.get(item_ptype, str)
+                py_type = List[item_type]
+            elif ptype == "object":
+                py_type = Dict[str, Any]
+            else:
+                py_type = _JSON_TO_PYTHON.get(ptype, str)
+
+            default_val = prop_data.get("default", ...)
+            if default_val is None:
+                py_type = Optional[py_type]
+
+            pydantic_fields[prop_name] = (
+                py_type,
+                Field(default=default_val, description=prop_data.get("description", "")),
+            )
+
+        ModelClass = create_model(f"{name}_args", **pydantic_fields)
+
+        def tool_wrapper(args: ModelClass) -> dict:
+            return handler.callback(**args.model_dump())
+
+        tool_wrapper.__name__ = name
+        tool_wrapper.__doc__ = description
+        sig = inspect.signature(tool_wrapper)
+        new_param = inspect.Parameter(
+            "args", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=ModelClass
+        )
+        tool_wrapper.__signature__ = sig.replace(parameters=(new_param,))
+        mcp.add_tool(tool_wrapper)

pythia/repository.py

@@ -0,0 +1,35 @@
+import copy
+from abc import ABC, abstractmethod
+
+from pythia.datasource import DataSource
+
+
+class Repository(ABC):
+    """Data access layer. Wraps a DataSource and exposes a get() method. Subclass names must end with 'Repository'."""
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if not cls.__name__.endswith("Repository"):
+            raise TypeError(
+                f"Repository subclasses must end with 'Repository' "
+                f"(got: '{cls.__name__}'). Rename to '{cls.__name__}Repository'."
+            )
+
+    def __init__(self, data_source: DataSource = None):
+        if data_source is not None:
+            resolved = data_source
+        else:
+            default = getattr(type(self), "data_source", None)
+            resolved = copy.copy(default)
+
+        if not resolved:
+            raise ValueError(f"{self.__class__.__name__}: data_source is required")
+        if not isinstance(resolved, DataSource):
+            raise ValueError(
+                f"{self.__class__.__name__}: data_source must be a DataSource instance"
+            )
+        self.data_source = resolved
+
+    @abstractmethod
+    def get(self, **kwargs):
+        pass

pythia/rest.py

@@ -0,0 +1,63 @@
+import datetime as dt
+import os
+from typing import Any, List
+
+from fastapi import FastAPI, HTTPException, Request
+from starlette.middleware.cors import CORSMiddleware
+
+
+def _validate_api_key(raw_key: str) -> bool:
+    env_keys = os.getenv("AUTH_API_KEY", "")
+    return bool(raw_key) and raw_key in [k.strip() for k in env_keys.split(",") if k.strip()]
+
+
+def _auth_dependency(request: Request):
+    if not os.getenv("AUTH_API_KEY"):
+        return
+    auth_header = request.headers.get("Authorization")
+    api_key = auth_header.split(" ")[1] if auth_header and auth_header.startswith("Bearer ") else None
+    if not api_key or not _validate_api_key(api_key):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+class RestApp:
+    """FastAPI application with CORS, auth dependency, and default routes (/health, /mcp/tools)."""
+
+    def __init__(self):
+        self.app = FastAPI()
+        cors_origins = [o.strip() for o in os.getenv("CORS_ORIGINS", "*").split(",")]
+        self.app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cors_origins,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+        self.url_handlers: List[Any] = []
+        self._setup_default_routes()
+
+    def _setup_default_routes(self):
+        @self.app.get("/mcp/tools")
+        def list_tools():
+            return {
+                "tools": [
+                    {
+                        "name": h.mcp_definition["name"],
+                        "description": h.mcp_definition["description"],
+                        "parameters": h.mcp_definition["parameters"],
+                        "returns": h.mcp_definition.get("returns", {}),
+                    }
+                    for h in self.url_handlers
+                ],
+                "server": "pythia",
+                "version": "0.1.0",
+            }
+
+        @self.app.get("/health")
+        def health_check():
+            return {
+                "status": "healthy",
+                "timestamp": dt.datetime.utcnow().isoformat(),
+            }
+
+    def register_handler(self, handler: Any):
+        self.url_handlers.append(handler)

pythia/server.py

@@ -0,0 +1,51 @@
+from typing import Any, Optional
+
+from pythia.rest import RestApp
+from pythia.mcp import McpApp
+
+
+class Server:
+    """Singleton that composes RestApp and McpApp. Entry point for starting the server and accessing registered endpoints."""
+
+    _instance: Optional["Server"] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if self._initialized:
+            return
+        self._rest = RestApp()
+        self._mcp = McpApp()
+        self._initialized = True
+
+    @property
+    def app(self):
+        return self._rest.app
+
+    @property
+    def url_handlers(self):
+        return self._rest.url_handlers
+
+    def register_url_handler(self, handler: Any):
+        self._rest.register_handler(handler)
+
+    def start(self, host: str = "0.0.0.0", port: int = 5000, reload: bool = False):
+        import uvicorn
+        uvicorn.run(self.app, host=host, port=port, reload=reload)
+
+    def get_mcp(self):
+        return self._mcp.build(self.url_handlers)
+
+    @classmethod
+    def get_instance(cls) -> "Server":
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def _reset(cls):
+        cls._instance = None

pythia/service.py

@@ -0,0 +1,35 @@
+import copy
+from abc import ABC
+
+from pythia.repository import Repository
+
+
+class Service(ABC):
+    """Business logic layer. Auto-discovers and copies Repository class attributes with DI support. Subclass names must end with 'Service'."""
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if not cls.__name__.endswith("Service"):
+            raise TypeError(
+                f"Service subclasses must end with 'Service' "
+                f"(got: '{cls.__name__}'). Rename to '{cls.__name__}Service'."
+            )
+        has_repo = any(
+            isinstance(v, Repository)
+            for klass in cls.__mro__
+            if klass not in (Service, object)
+            for v in vars(klass).values()
+        )
+        if not has_repo:
+            raise TypeError(
+                f"{cls.__name__}: must define at least one Repository instance "
+                f"as a class attribute."
+            )
+
+    def __init__(self, **overrides):
+        seen = set()
+        for klass in type(self).__mro__:
+            for name, value in vars(klass).items():
+                if name not in seen and isinstance(value, Repository):
+                    seen.add(name)
+                    setattr(self, name, overrides.get(name, copy.copy(value)))

pythia/types.py

@@ -0,0 +1,22 @@
+from typing import Any, Dict, TypedDict
+
+
+class McpProperty(TypedDict, total=False):
+    type: str
+    description: str
+    default: Any
+    items: Dict[str, Any]
+
+
+class McpParameters(TypedDict, total=False):
+    properties: Dict[str, McpProperty]
+
+
+class _McpDefinitionBase(TypedDict):
+    name: str
+    description: str
+
+
+class McpDefinition(_McpDefinitionBase, total=False):
+    parameters: McpParameters
+    returns: Dict[str, Any]

restmcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: restmcp
+Version: 0.1.0
+Summary: Python framework for building MCP servers with a layered architecture and REST compatibility
+Project-URL: Homepage, https://github.com/JorgeHSantana/Pythia
+Project-URL: Repository, https://github.com/JorgeHSantana/Pythia
+Project-URL: Bug Tracker, https://github.com/JorgeHSantana/Pythia/issues
+Author-email: Jorge Henrique Moreira Santana <jorge.henrique.moreira.santana@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,async,fastapi,framework,llm,mcp,rest,server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: fastapi>=0.100
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: uvicorn[standard]>=0.20
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# restmcp
+
+> One framework. MCP tools and REST endpoints, auto-registered.
+
+Python framework for building **MCP servers** with a layered architecture and REST compatibility.  
+Annotated classes become MCP tools and HTTP endpoints: auto-registered, dependency-injected, sync/async agnostic.
+
+---
+
+## Architecture
+
+```mermaid
+graph LR
+    LLM["🤖 LLM / Client"] -->|"HTTP or MCP"| EP["Endpoint"]
+    EP --> SV["Service"]
+    SV --> RP["Repository"]
+    RP --> DS["DataSource"]
+    DS --> EX[("External\nAPI / DB")]
+
+    style EP fill:#4f46e5,color:#fff,stroke:none
+    style SV fill:#7c3aed,color:#fff,stroke:none
+    style RP fill:#9333ea,color:#fff,stroke:none
+    style DS fill:#a855f7,color:#fff,stroke:none
+```
+
+Each layer knows only the layer directly below it. Every class name is suffix-enforced at import time: a typo raises `TypeError` before the server starts.
+
+---
+
+## Installation
+
+```bash
+pip install restmcp
+```
+
+---
+
+## Quick start
+
+```bash
+pythia new my-server
+cd my-server
+pip install -e .
+python main.py
+```
+
+Generated structure:
+
+```
+my-server/
+├── datasource/        # external connections (APIs, databases)
+├── models/            # domain entities (Pydantic)
+├── repositories/      # data access layer
+├── services/          # business logic
+├── tools/             # internal utilities
+├── urls/              # endpoint definitions (auto-discovery)
+├── main.py
+└── pyproject.toml
+```
+
+---
+
+## How it works
+
+```mermaid
+sequenceDiagram
+    participant C as Client / LLM
+    participant E as Endpoint
+    participant S as Service
+    participant R as Repository
+    participant D as DataSource
+
+    C->>E: POST /api/get-product {"product_id": "1"}
+    E->>S: service.execute(product_id="1")
+    S->>R: repo.get(product_id="1")
+    R->>D: data_source.fetch("1")
+    D-->>R: raw dict
+    R-->>S: ProductEntity
+    S-->>E: result dict
+    E-->>C: {"tool": "get_product", "result": {...}, "success": true}
+```
+
+---
+
+## Base classes
+
+### `DataSource`
+
+Abstracts the connection to an external data source (REST API, database, file).  
+**Rule:** class name must end with `DataSource`.
+
+```python
+import httpx
+from pythia import DataSource
+
+class ProductApiDataSource(DataSource):
+    base_url = "https://api.example.com"
+
+    async def fetch(self, product_id: str) -> dict:
+        async with httpx.AsyncClient() as client:
+            r = await client.get(f"{self.base_url}/products/{product_id}")
+            r.raise_for_status()
+            return r.json()
+```
+
+---
+
+### `Entity`
+
+Structured domain data backed by Pydantic. Automatic type validation.  
+**Rule:** class name must end with `Entity`.
+
+```python
+from pythia import Entity
+
+class ProductEntity(Entity):
+    id:    str
+    name:  str
+    price: float
+```
+
+---
+
+### `Repository`
+
+Fetches data via a `DataSource` and returns `Entity` objects. One source, one data type.  
+**Rules:** name ends with `Repository`; must declare `data_source` as class attribute; must implement `get()`.
+
+```python
+from pythia import Repository
+from datasource.product_api import ProductApiDataSource
+from models.product import ProductEntity
+
+class ProductRepository(Repository):
+    data_source = ProductApiDataSource()
+
+    async def get(self, product_id: str) -> ProductEntity:
+        raw = await self.data_source.fetch(product_id)
+        return ProductEntity(**raw)
+```
+
+**Dependency injection:**
+
+```python
+repo = ProductRepository()                              # uses real DataSource
+repo = ProductRepository(data_source=MockDataSource())  # injects mock for tests
+```
+
+`Repository.__init__` uses `copy.copy()` of the class attribute: instances are always isolated.
+
+---
+
+### `Service`
+
+Orchestrates business logic. Where joins, transformations, and multi-source rules live.  
+**Rules:** name ends with `Service`; must declare at least one `Repository` as class attribute.
+
+```python
+from pythia import Service
+from repositories.product import ProductRepository
+
+class GetProductService(Service):
+    repo = ProductRepository()
+
+    async def execute(self, product_id: str) -> dict:
+        product = await self.repo.get(product_id=product_id)
+        return product.model_dump()
+```
+
+**Dependency injection:**
+
+```python
+svc = GetProductService()                       # production
+svc = GetProductService(repo=MockRepository())  # test
+```
+
+Repository class attributes are auto-discovered via MRO and isolated per instance.
+
+---
+
+### `Endpoint`
+
+HTTP + MCP route. **Auto-registers on class definition**: no manual wiring needed.  
+**Rules:** name ends with `Endpoint`; must declare `mcp_definition`, `url`, `method`, and `callback`.
+
+```python
+from pythia import Endpoint
+from services.product import GetProductService
+
+class GetProductEndpoint(Endpoint):
+    mcp_definition = {
+        "name":        "get_product",
+        "description": "Returns a product by ID",
+        "parameters": {
+            "properties": {
+                "product_id": {"type": "string", "description": "Product ID"},
+            },
+        },
+    }
+    url    = "/api/get-product"
+    method = "POST"
+
+    async def callback(self, product_id: str) -> dict:
+        return await GetProductService().execute(product_id)
+```
+
+Defining the class is enough. The route is registered on the `Server` singleton the moment Python processes the class body.
+
+**Disabling an endpoint:**
+
+```python
+class GetProductEndpoint(Endpoint):
+    disabled = True  # skips auto-registration; can still be instantiated manually
+    ...
+```
+
+**Abstract base classes** (missing any required attribute) are never auto-registered:
+
+```python
+class BaseAuthEndpoint(Endpoint):
+    method = "POST"
+    def callback(self, **kwargs): ...
+# ↑ not registered: url and mcp_definition are missing
+
+class GetUserEndpoint(BaseAuthEndpoint):
+    mcp_definition = { ... }
+    url = "/api/get-user"
+# ↑ registered automatically: all required attributes present
+```
+
+**Sync and async callbacks** are both supported: pythia detects and handles either:
+
+```python
+# sync: runs in a thread pool, does not block the event loop
+def callback(self, product_id: str) -> dict:
+    return requests.get(f"https://api.example.com/products/{product_id}").json()
+
+# async: awaited directly; use asyncio.gather for parallel I/O
+async def callback(self, product_id: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        r = await client.get(f"https://api.example.com/products/{product_id}")
+        return r.json()
+```
+
+**Response format:**
+
+```json
+{ "tool": "get_product", "result": { ... }, "success": true }
+```
+
+```json
+{ "tool": "get_product", "error": "not found", "error_type": "NotFoundError", "success": false }
+```
+
+---
+
+### `Server`
+
+Singleton with dual-mode: HTTP via FastAPI/uvicorn or MCP protocol via FastMCP.
+
+```python
+from pythia import Server
+import urls  # triggers auto-discovery of all endpoint modules
+
+server = Server.get_instance()
+
+if __name__ == "__main__":
+    server.start(host="0.0.0.0", port=5000)
+```
+
+```python
+# MCP mode
+mcp = server.get_mcp()
+```
+
+**Built-in routes:**
+
+| Route | Method | Auth required |
+|-------|--------|---------------|
+| `/health` | GET | No |
+| `/mcp/tools` | GET | No |
+| _your endpoints_ | POST | Yes (if `AUTH_API_KEY` is set) |
+
+---
+
+## Exceptions
+
+Raised inside `callback`: caught by `Endpoint` and converted to HTTP responses automatically.
+
+```python
+from pythia import ValidationError, NotFoundError
+
+raise ValidationError("product_id is required")  # → HTTP 400
+raise NotFoundError("Product not found")          # → HTTP 404
+```
+
+```mermaid
+graph TD
+    PythiaException --> ValidationError["ValidationError (400)"]
+    PythiaException --> NotFoundError["NotFoundError (404)"]
+```
+
+---
+
+## Testing with injection
+
+```python
+from pythia import DataSource
+from repositories.product import ProductRepository
+from services.product import GetProductService
+
+class FakeProductApiDataSource(DataSource):
+    async def fetch(self, product_id: str) -> dict:
+        return {"id": product_id, "name": "Test Widget", "price": 1.99}
+
+def test_get_product():
+    svc = GetProductService(repo=ProductRepository(data_source=FakeProductApiDataSource()))
+    result = svc.execute(product_id="1")
+    assert result["name"] == "Test Widget"
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AUTH_API_KEY` | _(disabled)_ | Bearer token. Multiple keys supported comma-separated. |
+| `CORS_ORIGINS` | `*` | Allowed origins. Multiple values supported comma-separated. |
+| `LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+
+---
+
+## Naming conventions
+
+All base classes enforce a suffix. Violating it raises `TypeError` at import time: before the server starts.
+
+| Base class | Required suffix | Example |
+|------------|----------------|---------|
+| `DataSource` | `*DataSource` | `ProductApiDataSource` |
+| `Entity` | `*Entity` | `ProductEntity` |
+| `Repository` | `*Repository` | `ProductRepository` |
+| `Service` | `*Service` | `GetProductService` |
+| `Endpoint` | `*Endpoint` | `GetProductEndpoint` |
+
+---
+
+## Dependencies
+
+```
+fastapi    >= 0.100
+uvicorn    >= 0.20
+fastmcp    >= 2.0
+pydantic   >= 2.0
+click      >= 8.0
+```
+
+---
+
+## Author
+
+**Jorge Henrique Moreira Santana**  
+Electrical Engineer, Postgraduate in Artificial Intelligence  
+[LinkedIn](https://www.linkedin.com/in/jorge-santana-b246874a/) · jorge.henrique.moreira.santana@gmail.com
+
+---
+
+## License
+
+[MIT](LICENSE)

restmcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+pythia/__init__.py,sha256=-qBANeCi5gF2DpvgN4JHcQtLWlphZlxvFKFBCN8dOVM,543
+pythia/datasource.py,sha256=yrq96uiFzF4NBoxgHXuxDOd9MNsqwxsVKGUnRS1CqUA,669
+pythia/endpoint.py,sha256=IOt8xSSPDMKTycjqJLPK_u38N_64AK4YYXDNVVM9ZW4,5023
+pythia/entity.py,sha256=yGnit4sD18-n0h-4Umv3QvTf5bo6yFhPlu2IyRaOrwI,474
+pythia/exceptions.py,sha256=sgdbx6PVbYgxXgm1-4I8GUAxgSfPx9IfWlYL11rACRU,549
+pythia/logging.py,sha256=iwGP3p-NrBcvFEL2iEn-ztUHu7e7h3v52aaUBUMVSg8,1174
+pythia/mcp.py,sha256=qkCy18Vpm4Y5Y1ZtyWmRHyUKb7edX6YgGbTWsLWuVOU,2205
+pythia/repository.py,sha256=JXd4T1yCrQJ1tWcEbB12BNv94kfbi_lWq1YA9kJsA1M,1204
+pythia/rest.py,sha256=36L29-K003ZjZnrPe5ytV0BZDpSoPbrCQzSefUyXzig,2143
+pythia/server.py,sha256=n5V43cj8pQ3cqdClqgZ0IA5xUZ6bGGd4wbjxVuFQhuU,1342
+pythia/service.py,sha256=Nflwls_7YNBFLasFmcBL1e0bGZOdBLZobJ4-CDjGTrs,1284
+pythia/types.py,sha256=S9seymj7EzMtRVEOPe8MqkZDwYwZ66yFY4YykO8JPJ8,437
+pythia/cli/__init__.py,sha256=lnmyKZ0xDWdckiWuinpRG1eNnd8-RwEHtpwHX9j0nrY,189
+pythia/cli/new.py,sha256=DajdF4VpEszs5-JO-gn6QGvsNNJsEL9ZoYLn11zP_fg,1504
+restmcp-0.1.0.dist-info/METADATA,sha256=GhMc3KR9N6HuAxC6Gg486xvDSqNB7-Is7WNWkeo7tkk,10892
+restmcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+restmcp-0.1.0.dist-info/entry_points.txt,sha256=2yMZUEAaNAPdOuTgqC-wfHLDKbrlR3u8JkMcoqd6YoE,42
+restmcp-0.1.0.dist-info/licenses/LICENSE,sha256=3KqaiOmu_5URYxkqg7EPIQGTd4ckqsu7_P5oCBQ7yuY,1070
+restmcp-0.1.0.dist-info/RECORD,,

restmcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

restmcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pythia = pythia.cli:app

restmcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JorgeHSantana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.