restmcp 0.1.2__tar.gz

restmcp-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Test & Publish
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=restmcp --cov-report=xml
+      - uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+
+  publish-testpypi:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

restmcp-0.1.2/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+wheels/
+*.whl
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# pytest / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Type checkers
+.mypy_cache/
+.dmypy.json
+.pytype/
+.pyre/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# hatch / build
+.hatch/
+
+# internal dev docs
+docs/superpowers/

restmcp-0.1.2/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.

restmcp-0.1.2/PKG-INFO

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: restmcp
+Version: 0.1.2
+Summary: Python framework for building MCP servers with a layered architecture and REST compatibility
+Project-URL: Homepage, https://github.com/JorgeHSantana/restmcp
+Project-URL: Repository, https://github.com/JorgeHSantana/restmcp
+Project-URL: Bug Tracker, https://github.com/JorgeHSantana/restmcp/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'
+Requires-Dist: requests>=2.28; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# restmcp
+
+[![codecov](https://codecov.io/gh/JorgeHSantana/restmcp/branch/main/graph/badge.svg)](https://codecov.io/gh/JorgeHSantana/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
+restmcp 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 restmcp 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 restmcp 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 restmcp 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 restmcp 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 restmcp 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: restmcp 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 restmcp 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 restmcp 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 restmcp 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)