toolaccess 0.1.0__tar.gz

toolaccess-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whogben
+
+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.

toolaccess-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: toolaccess
+Version: 0.1.0
+Summary: Make your custom tools accessible across multiple protocols, including MCP, REST and CLI.
+Project-URL: Homepage, https://github.com/whogben/toolaccess
+Project-URL: Repository, https://github.com/whogben/toolaccess
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: fastmcp
+Requires-Dist: pydantic
+Requires-Dist: typer
+Requires-Dist: uvicorn
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: license-file
+
+# toolaccess
+
+Define your Python functions once, expose them as **REST APIs**, **MCP servers**, and **CLI commands** — simultaneously, with zero boilerplate duplication.
+
+## When to use this
+
+You have Python functions that need to be callable from more than one interface. Common scenarios:
+
+- **AI/LLM tool servers** — you want the same tools available over MCP (for agents) and REST (for web apps) and CLI (for local testing).
+- **Internal tooling** — a set of utility functions your team invokes from scripts, HTTP clients, and AI assistants.
+- **Rapid prototyping** — skip the plumbing and get a working API + MCP server + CLI in minutes.
+
+Without `toolaccess` you'd write separate FastAPI routes, a FastMCP server, and Typer commands that all call the same underlying code. This library removes that duplication.
+
+## Install
+
+```bash
+pip install toolaccess
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from toolaccess import (
+    ServerManager,
+    ToolService,
+    ToolDefinition,
+    OpenAPIServer,
+    SSEMCPServer,
+    CLIServer,
+)
+
+# 1. Write plain functions (sync or async)
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+async def greet(name: str) -> str:
+    """Return a greeting."""
+    return f"Hello, {name}!"
+
+# 2. Group them into a service
+service = ToolService("math", [add, greet])
+
+# 3. Create servers and mount the service
+rest = OpenAPIServer(path_prefix="/api", title="Math API")
+rest.mount(service)
+
+mcp = SSEMCPServer("math")
+mcp.mount(service)
+
+cli = CLIServer("math")
+cli.mount(service)
+
+# 4. Wire everything into the manager
+manager = ServerManager(name="my-tools")
+manager.add_server(rest)
+manager.add_server(mcp)
+manager.add_server(cli)
+
+# 5. Run
+manager.run()
+```
+
+That single file gives you:
+
+| Interface | Access |
+|---|---|
+| REST API | `POST /api/add`, `POST /api/greet` |
+| OpenAPI docs | `GET /api/docs` |
+| MCP (SSE) | `http://localhost:8000/mcp/math/sse` |
+| MCP (stdio) | `python app.py mcp-run --name math` |
+| CLI | `python app.py math add 1 2` |
+| Health check | `GET /health` |
+
+### Starting the HTTP server
+
+```bash
+python app.py start                        # default 127.0.0.1:8000
+python app.py start --host 0.0.0.0 --port 9000
+```
+
+### Running MCP over stdio
+
+```bash
+python app.py mcp-run --name math
+```
+
+Use this when connecting from Claude Desktop, Cursor, or any MCP client that expects a stdio transport.
+
+## Core concepts
+
+### ToolDefinition
+
+Wraps a callable with metadata. If you pass a bare function to `ToolService`, one is created automatically using the function name and docstring. Use it explicitly when you need control over the HTTP method or name:
+
+```python
+ToolDefinition(func=add, name="add_numbers", http_method="POST", description="Sum two ints")
+```
+
+### ToolService
+
+A named group of tools. Mount the same service onto multiple servers to keep them in sync:
+
+```python
+service = ToolService("admin", [check_health, restart_worker])
+```
+
+### Servers
+
+| Class | Protocol | Notes |
+|---|---|---|
+| `OpenAPIServer` | HTTP / REST | Backed by FastAPI. Set `path_prefix` to namespace routes. |
+| `SSEMCPServer` | MCP (SSE + stdio) | Backed by FastMCP. Mounted at `/mcp/{name}/sse`. |
+| `CLIServer` | CLI | Backed by Typer. Async functions are handled automatically. |
+
+### ServerManager
+
+The runtime host. It owns a FastAPI app, a Typer CLI, and a dynamic ASGI dispatcher that routes requests to the correct sub-app by path prefix.
+
+Servers can be added and removed at runtime:
+
+```python
+manager.add_server(new_api)    # immediately routable
+manager.remove_server(new_api) # immediately gone
+```
+
+## Multiple isolated groups
+
+You can create separate servers for different audiences and mount different services onto each:
+
+```python
+public_api = OpenAPIServer("/public", "Public API")
+public_api.mount(public_service)
+
+admin_api = OpenAPIServer("/admin", "Admin API")
+admin_api.mount(admin_service)
+
+manager.add_server(public_api)
+manager.add_server(admin_api)
+```
+
+The same pattern works for MCP — create multiple `SSEMCPServer` instances with different names.
+
+## Lifespan support
+
+Pass an async context manager to `ServerManager` to run setup/teardown logic (database connections, model loading, etc.). The lifespan is entered for both the HTTP server and CLI command execution:
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app):
+    db = await connect_db()
+    yield
+    await db.close()
+
+manager = ServerManager(name="my-service", lifespan=lifespan)
+```
+
+## Mounting custom ASGI apps
+
+Use `MountableApp` to add an existing FastAPI or ASGI application alongside your tool servers:
+
+```python
+from toolaccess.toolaccess import MountableApp
+from fastapi import FastAPI
+
+dashboard = FastAPI()
+
+@dashboard.get("/")
+async def index():
+    return {"page": "dashboard"}
+
+manager.add_server(MountableApp(dashboard, path_prefix="/dashboard", name="dashboard"))
+```
+
+## Requirements
+
+- Python >= 3.10
+- fastapi
+- fastmcp
+- pydantic
+- typer
+- uvicorn
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

toolaccess-0.1.0/README.md

@@ -0,0 +1,198 @@
+# toolaccess
+
+Define your Python functions once, expose them as **REST APIs**, **MCP servers**, and **CLI commands** — simultaneously, with zero boilerplate duplication.
+
+## When to use this
+
+You have Python functions that need to be callable from more than one interface. Common scenarios:
+
+- **AI/LLM tool servers** — you want the same tools available over MCP (for agents) and REST (for web apps) and CLI (for local testing).
+- **Internal tooling** — a set of utility functions your team invokes from scripts, HTTP clients, and AI assistants.
+- **Rapid prototyping** — skip the plumbing and get a working API + MCP server + CLI in minutes.
+
+Without `toolaccess` you'd write separate FastAPI routes, a FastMCP server, and Typer commands that all call the same underlying code. This library removes that duplication.
+
+## Install
+
+```bash
+pip install toolaccess
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from toolaccess import (
+    ServerManager,
+    ToolService,
+    ToolDefinition,
+    OpenAPIServer,
+    SSEMCPServer,
+    CLIServer,
+)
+
+# 1. Write plain functions (sync or async)
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+async def greet(name: str) -> str:
+    """Return a greeting."""
+    return f"Hello, {name}!"
+
+# 2. Group them into a service
+service = ToolService("math", [add, greet])
+
+# 3. Create servers and mount the service
+rest = OpenAPIServer(path_prefix="/api", title="Math API")
+rest.mount(service)
+
+mcp = SSEMCPServer("math")
+mcp.mount(service)
+
+cli = CLIServer("math")
+cli.mount(service)
+
+# 4. Wire everything into the manager
+manager = ServerManager(name="my-tools")
+manager.add_server(rest)
+manager.add_server(mcp)
+manager.add_server(cli)
+
+# 5. Run
+manager.run()
+```
+
+That single file gives you:
+
+| Interface | Access |
+|---|---|
+| REST API | `POST /api/add`, `POST /api/greet` |
+| OpenAPI docs | `GET /api/docs` |
+| MCP (SSE) | `http://localhost:8000/mcp/math/sse` |
+| MCP (stdio) | `python app.py mcp-run --name math` |
+| CLI | `python app.py math add 1 2` |
+| Health check | `GET /health` |
+
+### Starting the HTTP server
+
+```bash
+python app.py start                        # default 127.0.0.1:8000
+python app.py start --host 0.0.0.0 --port 9000
+```
+
+### Running MCP over stdio
+
+```bash
+python app.py mcp-run --name math
+```
+
+Use this when connecting from Claude Desktop, Cursor, or any MCP client that expects a stdio transport.
+
+## Core concepts
+
+### ToolDefinition
+
+Wraps a callable with metadata. If you pass a bare function to `ToolService`, one is created automatically using the function name and docstring. Use it explicitly when you need control over the HTTP method or name:
+
+```python
+ToolDefinition(func=add, name="add_numbers", http_method="POST", description="Sum two ints")
+```
+
+### ToolService
+
+A named group of tools. Mount the same service onto multiple servers to keep them in sync:
+
+```python
+service = ToolService("admin", [check_health, restart_worker])
+```
+
+### Servers
+
+| Class | Protocol | Notes |
+|---|---|---|
+| `OpenAPIServer` | HTTP / REST | Backed by FastAPI. Set `path_prefix` to namespace routes. |
+| `SSEMCPServer` | MCP (SSE + stdio) | Backed by FastMCP. Mounted at `/mcp/{name}/sse`. |
+| `CLIServer` | CLI | Backed by Typer. Async functions are handled automatically. |
+
+### ServerManager
+
+The runtime host. It owns a FastAPI app, a Typer CLI, and a dynamic ASGI dispatcher that routes requests to the correct sub-app by path prefix.
+
+Servers can be added and removed at runtime:
+
+```python
+manager.add_server(new_api)    # immediately routable
+manager.remove_server(new_api) # immediately gone
+```
+
+## Multiple isolated groups
+
+You can create separate servers for different audiences and mount different services onto each:
+
+```python
+public_api = OpenAPIServer("/public", "Public API")
+public_api.mount(public_service)
+
+admin_api = OpenAPIServer("/admin", "Admin API")
+admin_api.mount(admin_service)
+
+manager.add_server(public_api)
+manager.add_server(admin_api)
+```
+
+The same pattern works for MCP — create multiple `SSEMCPServer` instances with different names.
+
+## Lifespan support
+
+Pass an async context manager to `ServerManager` to run setup/teardown logic (database connections, model loading, etc.). The lifespan is entered for both the HTTP server and CLI command execution:
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app):
+    db = await connect_db()
+    yield
+    await db.close()
+
+manager = ServerManager(name="my-service", lifespan=lifespan)
+```
+
+## Mounting custom ASGI apps
+
+Use `MountableApp` to add an existing FastAPI or ASGI application alongside your tool servers:
+
+```python
+from toolaccess.toolaccess import MountableApp
+from fastapi import FastAPI
+
+dashboard = FastAPI()
+
+@dashboard.get("/")
+async def index():
+    return {"page": "dashboard"}
+
+manager.add_server(MountableApp(dashboard, path_prefix="/dashboard", name="dashboard"))
+```
+
+## Requirements
+
+- Python >= 3.10
+- fastapi
+- fastmcp
+- pydantic
+- typer
+- uvicorn
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

toolaccess-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "toolaccess"
+version = "0.1.0"
+description = "Make your custom tools accessible across multiple protocols, including MCP, REST and CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi",
+    "fastmcp",
+    "pydantic",
+    "typer",
+    "uvicorn",
+]
+
+[project.urls]
+Homepage = "https://github.com/whogben/toolaccess"
+Repository = "https://github.com/whogben/toolaccess"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

toolaccess-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

toolaccess-0.1.0/src/toolaccess/__init__.py

@@ -0,0 +1,17 @@
+from .toolaccess import (
+    ServerManager,
+    ToolService,
+    ToolDefinition,
+    OpenAPIServer,
+    SSEMCPServer,
+    CLIServer,
+)
+
+__all__ = [
+    "ServerManager",
+    "ToolService",
+    "ToolDefinition",
+    "OpenAPIServer",
+    "SSEMCPServer",
+    "CLIServer",
+]

toolaccess-0.1.0/src/toolaccess/toolaccess.py

@@ -0,0 +1,417 @@
+import inspect
+import asyncio
+import json
+import logging
+from functools import wraps
+from typing import Any, Callable, Literal, Union, get_origin, get_args
+
+import typer
+import uvicorn
+from fastapi import FastAPI
+from fastmcp import FastMCP
+from dataclasses import dataclass, field
+from abc import ABC, abstractmethod
+from starlette.types import Scope, Receive, Send
+from starlette.responses import Response
+
+"""
+Generic Tool Server Utility (Polymorphic Server Model)
+Provides reusable components for exposing Python functions as tools via
+CLI, OpenAPI (REST), and MCP (SSE/Stdio).
+"""
+
+logger = logging.getLogger(__name__)
+
+# --- 1. Tool Definition & Service ---
+
+HttpMethod = Literal["GET", "POST", "PUT", "DELETE", "PATCH"]
+
+
+@dataclass
+class ToolDefinition:
+    """Metadata for a single tool function."""
+
+    func: Callable
+    name: str
+    http_method: HttpMethod = "POST"
+    description: str | None = None
+
+    def __post_init__(self):
+        if self.description is None and self.func.__doc__:
+            self.description = inspect.cleandoc(self.func.__doc__)
+
+
+class ToolService:
+    """A collection of tools to be exposed together."""
+
+    def __init__(self, name: str, tools: list[Callable | ToolDefinition]):
+        self.name = name
+        self.tools: list[ToolDefinition] = []
+        for t in tools:
+            if isinstance(t, ToolDefinition):
+                self.tools.append(t)
+            else:
+                self.tools.append(ToolDefinition(func=t, name=t.__name__))
+
+
+# --- 2. Abstract Base Server ---
+
+
+class BaseServer(ABC):
+    """Abstract base for any server interface."""
+
+    @abstractmethod
+    def mount(self, service: ToolService):
+        """Add a service's tools to this server."""
+        pass
+
+    @abstractmethod
+    def register_to(self, manager: "ServerManager"):
+        """Hook this server into the runtime manager."""
+        pass
+
+
+# --- 3. Concrete Servers ---
+
+METHOD_ROUTERS: dict[str, Callable] = {
+    "GET": FastAPI.get,
+    "POST": FastAPI.post,
+    "PUT": FastAPI.put,
+    "DELETE": FastAPI.delete,
+    "PATCH": FastAPI.patch,
+}
+
+
+class OpenAPIServer(BaseServer):
+    """Exposes tools via FastAPI sub-application."""
+
+    def __init__(self, path_prefix: str = "", title: str = "API"):
+        self.path_prefix = path_prefix
+        self.app = FastAPI(title=title)
+
+    def mount(self, service: ToolService):
+        for tool in service.tools:
+            self._add_route(tool)
+
+    def _add_route(self, tool: ToolDefinition):
+        router = METHOD_ROUTERS.get(tool.http_method, FastAPI.post)
+        router(self.app, f"/{tool.name}", name=tool.name, description=tool.description)(
+            tool.func
+        )
+
+    def register_to(self, manager: "ServerManager"):
+        pass
+
+
+class SSEMCPServer(BaseServer):
+    """Exposes tools via FastMCP (SSE & Stdio capability)."""
+
+    def __init__(self, name: str = "default"):
+        self.name = name
+        self.mcp = FastMCP(name)
+
+    def mount(self, service: ToolService):
+        for tool in service.tools:
+            # Wrap function to handle JSON string arguments from MCP clients
+            wrapped_func = _wrap_for_mcp(tool.func)
+            self.mcp.tool(wrapped_func, name=tool.name, description=tool.description)
+
+    def register_to(self, manager: "ServerManager"):
+        manager.mcp_servers[self.name] = self.mcp
+
+
+class CLIServer(BaseServer):
+    """Exposes tools via Typer CLI."""
+
+    def __init__(self, name: str | None = None):
+        self.name = name
+        self.typer_app = typer.Typer(name=name) if name else typer.Typer()
+        self.manager: "ServerManager" | None = None
+
+    def mount(self, service: ToolService):
+        for tool in service.tools:
+            self._add_command(self.typer_app, tool)
+
+    def _add_command(self, app: typer.Typer, tool: ToolDefinition):
+        func = tool.func
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                async def runner():
+                    if self.manager and self.manager.lifespan_ctx:
+                        async with self.manager.lifespan_ctx(self.manager.app):
+                            return await func(*args, **kwargs)
+                    else:
+                        return await func(*args, **kwargs)
+
+                try:
+                    return asyncio.run(runner())
+                except KeyboardInterrupt:
+                    return None
+
+            wrapper.__signature__ = inspect.signature(func)
+            cli_func = wrapper
+        else:
+            cli_func = func
+        app.command(name=tool.name, help=tool.description)(cli_func)
+
+    def register_to(self, manager: "ServerManager"):
+        self.manager = manager
+        manager.cli.add_typer(self.typer_app, name=self.name)
+
+
+class MountableApp(BaseServer):
+    """
+    Wraps an existing FastAPI/ASGI application to be mounted by the ServerManager.
+    Useful for custom web interfaces, separate API sub-apps, or static file servers.
+    """
+
+    def __init__(self, app: FastAPI, path_prefix: str = "", name: str = "app"):
+        self.app = app
+        self.path_prefix = path_prefix
+        self.name = name
+
+    def mount(self, service: ToolService):
+        """
+        MountableApp generally doesn't accept ToolServices, as its routes
+        are defined internally. We can leave this empty or log a warning.
+        """
+        pass
+
+    def register_to(self, manager: "ServerManager"):
+        # No special registration needed, the Dispatcher handles it
+        pass
+
+
+# --- 4. Server Manager (Runtime) ---
+
+
+class DynamicDispatcher:
+    """ASGI Application that dynamically dispatches requests to sub-apps."""
+
+    def __init__(self, manager: "ServerManager"):
+        self.manager = manager
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        if scope["type"] != "http":
+            await Response("Not Found", status_code=404)(scope, receive, send)
+            return
+
+        path = scope["path"]
+        logger.debug(f"Dispatching path={path}")
+
+        # Collect matches (server, prefix_length)
+        matches = []
+        for server in self.manager.active_servers.values():
+            if isinstance(server, OpenAPIServer):
+                prefix = server.path_prefix.strip("/")
+                if not prefix:
+                    continue
+                check_prefix = f"/{prefix}"
+                if path.startswith(check_prefix):
+                    remaining = path[len(check_prefix) :]
+                    if not remaining or remaining.startswith("/"):
+                        matches.append((server, len(check_prefix)))
+
+            elif isinstance(server, SSEMCPServer):
+                prefix = f"/mcp/{server.name}"
+                if path.startswith(prefix):
+                    remaining = path[len(prefix) :]
+                    if not remaining or remaining.startswith("/"):
+                        matches.append((server, len(prefix)))
+
+            elif isinstance(server, MountableApp):
+                prefix = server.path_prefix.strip("/")
+                check_prefix = f"/{prefix}" if prefix else "/"
+                if path.startswith(check_prefix):
+                    # Special handling for root
+                    if check_prefix == "/":
+                        matches.append((server, 1))
+                    else:
+                        remaining = path[len(check_prefix) :]
+                        if not remaining or remaining.startswith("/"):
+                            matches.append((server, len(check_prefix)))
+
+        if not matches:
+            logger.debug("No match found")
+            await Response("Not Found", status_code=404)(scope, receive, send)
+            return
+
+        # Sort by specificity (longest prefix wins)
+        matches.sort(key=lambda x: x[1], reverse=True)
+        server, prefix_len = matches[0]
+
+        # Dispatch
+        if isinstance(server, OpenAPIServer):
+            prefix = server.path_prefix.strip("/")
+            check_prefix = f"/{prefix}"
+            scope["root_path"] = scope.get("root_path", "") + check_prefix
+            scope["path"] = path[prefix_len:] or "/"
+            await server.app(scope, receive, send)
+
+        elif isinstance(server, SSEMCPServer):
+            prefix = f"/mcp/{server.name}"
+            scope["root_path"] = scope.get("root_path", "") + prefix
+            scope["path"] = path[prefix_len:] or "/"
+            await server.mcp.http_app(transport="sse")(scope, receive, send)
+
+        elif isinstance(server, MountableApp):
+            prefix = server.path_prefix.strip("/")
+            check_prefix = f"/{prefix}" if prefix else ""
+            if check_prefix == "/":
+                check_prefix = ""  # Don't add trailing slash to root path
+
+            scope["root_path"] = scope.get("root_path", "") + check_prefix
+            scope["path"] = path[prefix_len:] if prefix_len > 1 else path
+            if not scope["path"]:
+                scope["path"] = "/"
+            await server.app(scope, receive, send)
+
+
+class ServerManager:
+    """The runtime host that manages all servers."""
+
+    def __init__(self, name: str = "service", lifespan: Callable | None = None):
+        self.name = name
+        self.lifespan_ctx = lifespan
+        self.app = FastAPI(title=name, lifespan=lifespan)
+        self.cli = typer.Typer(name=name)
+        self.mcp_servers: dict[str, FastMCP] = {}
+        self.active_servers: dict[str, BaseServer] = {}
+        self._add_infrastructure()
+        self.app.mount("/", DynamicDispatcher(self))
+
+    def add_server(self, server: BaseServer):
+        """Register a polymorphic server instance."""
+        self.active_servers[str(id(server))] = server
+        server.register_to(self)
+
+    def remove_server(self, server: BaseServer):
+        """Unregister a server instance."""
+        server_id = str(id(server))
+        if server_id in self.active_servers:
+            del self.active_servers[server_id]
+            if isinstance(server, SSEMCPServer) and server.name in self.mcp_servers:
+                del self.mcp_servers[server.name]
+
+    def _add_infrastructure(self):
+        @self.app.get("/health")
+        async def health():
+            """Health check endpoint listing all MCP servers."""
+            return {"mcp_servers": list(self.mcp_servers.keys())}
+
+        @self.cli.command()
+        def start(host: str = "127.0.0.1", port: int = 8000):
+            """Start the server (REST + MCP SSE)."""
+            print(f"🚀 {self.name} Server Starting...")
+            print(f"---------------------------------------------------")
+            print(f"📋 OpenAPI:           http://{host}:{port}/docs")
+            for mcp_name in self.mcp_servers:
+                print(f"🤖 MCP Server:        http://{host}:{port}/mcp/{mcp_name}/sse")
+
+            # Print URLs for MountableApps
+            for server in self.active_servers.values():
+                if isinstance(server, MountableApp):
+                    prefix = server.path_prefix if server.path_prefix else "/"
+                    print(f"🌐 Web App ({server.name}): http://{host}:{port}{prefix}")
+
+            print(f"---------------------------------------------------")
+            uvicorn.run(self.app, host=host, port=port)
+
+        @self.cli.command()
+        def mcp_run(name: str = "default"):
+            """Run an MCP server via Stdio."""
+            if name not in self.mcp_servers:
+                print(
+                    f"❌ MCP Server '{name}' not found. Available: {list(self.mcp_servers.keys())}"
+                )
+                return
+
+            async def run_stdio():
+                if self.lifespan_ctx:
+                    async with self.lifespan_ctx(self.app):
+                        await self.mcp_servers[name].run_stdio_async()
+                else:
+                    await self.mcp_servers[name].run_stdio_async()
+
+            try:
+                asyncio.run(run_stdio())
+            except KeyboardInterrupt:
+                return
+            except Exception as e:
+                print(f"Error running MCP stdio: {e}")
+                self.mcp_servers[name].run(transport="stdio")
+
+    def run(self):
+        """Entry point for the CLI."""
+        self.cli()
+
+
+# --- MISC UTILS ---
+
+
+def _wrap_for_mcp(func: Callable) -> Callable:
+    """
+    Wrap a function to pre-process arguments for MCP compatibility.
+
+    This ensures JSON strings are parsed into proper dicts before
+    the function is called, handling clients that serialize nested
+    objects as strings. It inspects the function signature to avoid
+    parsing arguments that are explicitly typed as strings.
+    """
+    sig = inspect.signature(func)
+
+    def process_kwargs(kwargs: dict[str, Any]) -> dict[str, Any]:
+        new_kwargs = {}
+        for k, v in kwargs.items():
+            # If the value is NOT a string, keep it as is
+            if not isinstance(v, str):
+                new_kwargs[k] = v
+                continue
+
+            # Check parameter type hint
+            param = sig.parameters.get(k)
+            should_skip = False
+
+            if param:
+                annotation = param.annotation
+                if annotation is str:
+                    should_skip = True
+                else:
+                    # Handle Optional[str] -> Union[str, None]
+                    origin = get_origin(annotation)
+                    if origin is Union:
+                        args = get_args(annotation)
+                        non_none = [a for a in args if a is not type(None)]
+                        if len(non_none) == 1 and non_none[0] is str:
+                            should_skip = True
+
+            if should_skip:
+                new_kwargs[k] = v
+            else:
+                try:
+                    # Only parse top-level string arguments
+                    new_kwargs[k] = json.loads(v)
+                except (json.JSONDecodeError, TypeError):
+                    new_kwargs[k] = v
+
+        return new_kwargs
+
+    if inspect.iscoroutinefunction(func):
+
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            return await func(*args, **process_kwargs(kwargs))
+
+        # Preserve signature for FastMCP schema generation
+        async_wrapper.__signature__ = sig
+        return async_wrapper
+    else:
+
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            return func(*args, **process_kwargs(kwargs))
+
+        sync_wrapper.__signature__ = sig
+        return sync_wrapper

toolaccess-0.1.0/src/toolaccess.egg-info/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: toolaccess
+Version: 0.1.0
+Summary: Make your custom tools accessible across multiple protocols, including MCP, REST and CLI.
+Project-URL: Homepage, https://github.com/whogben/toolaccess
+Project-URL: Repository, https://github.com/whogben/toolaccess
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: fastmcp
+Requires-Dist: pydantic
+Requires-Dist: typer
+Requires-Dist: uvicorn
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: license-file
+
+# toolaccess
+
+Define your Python functions once, expose them as **REST APIs**, **MCP servers**, and **CLI commands** — simultaneously, with zero boilerplate duplication.
+
+## When to use this
+
+You have Python functions that need to be callable from more than one interface. Common scenarios:
+
+- **AI/LLM tool servers** — you want the same tools available over MCP (for agents) and REST (for web apps) and CLI (for local testing).
+- **Internal tooling** — a set of utility functions your team invokes from scripts, HTTP clients, and AI assistants.
+- **Rapid prototyping** — skip the plumbing and get a working API + MCP server + CLI in minutes.
+
+Without `toolaccess` you'd write separate FastAPI routes, a FastMCP server, and Typer commands that all call the same underlying code. This library removes that duplication.
+
+## Install
+
+```bash
+pip install toolaccess
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from toolaccess import (
+    ServerManager,
+    ToolService,
+    ToolDefinition,
+    OpenAPIServer,
+    SSEMCPServer,
+    CLIServer,
+)
+
+# 1. Write plain functions (sync or async)
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+async def greet(name: str) -> str:
+    """Return a greeting."""
+    return f"Hello, {name}!"
+
+# 2. Group them into a service
+service = ToolService("math", [add, greet])
+
+# 3. Create servers and mount the service
+rest = OpenAPIServer(path_prefix="/api", title="Math API")
+rest.mount(service)
+
+mcp = SSEMCPServer("math")
+mcp.mount(service)
+
+cli = CLIServer("math")
+cli.mount(service)
+
+# 4. Wire everything into the manager
+manager = ServerManager(name="my-tools")
+manager.add_server(rest)
+manager.add_server(mcp)
+manager.add_server(cli)
+
+# 5. Run
+manager.run()
+```
+
+That single file gives you:
+
+| Interface | Access |
+|---|---|
+| REST API | `POST /api/add`, `POST /api/greet` |
+| OpenAPI docs | `GET /api/docs` |
+| MCP (SSE) | `http://localhost:8000/mcp/math/sse` |
+| MCP (stdio) | `python app.py mcp-run --name math` |
+| CLI | `python app.py math add 1 2` |
+| Health check | `GET /health` |
+
+### Starting the HTTP server
+
+```bash
+python app.py start                        # default 127.0.0.1:8000
+python app.py start --host 0.0.0.0 --port 9000
+```
+
+### Running MCP over stdio
+
+```bash
+python app.py mcp-run --name math
+```
+
+Use this when connecting from Claude Desktop, Cursor, or any MCP client that expects a stdio transport.
+
+## Core concepts
+
+### ToolDefinition
+
+Wraps a callable with metadata. If you pass a bare function to `ToolService`, one is created automatically using the function name and docstring. Use it explicitly when you need control over the HTTP method or name:
+
+```python
+ToolDefinition(func=add, name="add_numbers", http_method="POST", description="Sum two ints")
+```
+
+### ToolService
+
+A named group of tools. Mount the same service onto multiple servers to keep them in sync:
+
+```python
+service = ToolService("admin", [check_health, restart_worker])
+```
+
+### Servers
+
+| Class | Protocol | Notes |
+|---|---|---|
+| `OpenAPIServer` | HTTP / REST | Backed by FastAPI. Set `path_prefix` to namespace routes. |
+| `SSEMCPServer` | MCP (SSE + stdio) | Backed by FastMCP. Mounted at `/mcp/{name}/sse`. |
+| `CLIServer` | CLI | Backed by Typer. Async functions are handled automatically. |
+
+### ServerManager
+
+The runtime host. It owns a FastAPI app, a Typer CLI, and a dynamic ASGI dispatcher that routes requests to the correct sub-app by path prefix.
+
+Servers can be added and removed at runtime:
+
+```python
+manager.add_server(new_api)    # immediately routable
+manager.remove_server(new_api) # immediately gone
+```
+
+## Multiple isolated groups
+
+You can create separate servers for different audiences and mount different services onto each:
+
+```python
+public_api = OpenAPIServer("/public", "Public API")
+public_api.mount(public_service)
+
+admin_api = OpenAPIServer("/admin", "Admin API")
+admin_api.mount(admin_service)
+
+manager.add_server(public_api)
+manager.add_server(admin_api)
+```
+
+The same pattern works for MCP — create multiple `SSEMCPServer` instances with different names.
+
+## Lifespan support
+
+Pass an async context manager to `ServerManager` to run setup/teardown logic (database connections, model loading, etc.). The lifespan is entered for both the HTTP server and CLI command execution:
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app):
+    db = await connect_db()
+    yield
+    await db.close()
+
+manager = ServerManager(name="my-service", lifespan=lifespan)
+```
+
+## Mounting custom ASGI apps
+
+Use `MountableApp` to add an existing FastAPI or ASGI application alongside your tool servers:
+
+```python
+from toolaccess.toolaccess import MountableApp
+from fastapi import FastAPI
+
+dashboard = FastAPI()
+
+@dashboard.get("/")
+async def index():
+    return {"page": "dashboard"}
+
+manager.add_server(MountableApp(dashboard, path_prefix="/dashboard", name="dashboard"))
+```
+
+## Requirements
+
+- Python >= 3.10
+- fastapi
+- fastmcp
+- pydantic
+- typer
+- uvicorn
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

toolaccess-0.1.0/src/toolaccess.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/toolaccess/__init__.py
+src/toolaccess/toolaccess.py
+src/toolaccess.egg-info/PKG-INFO
+src/toolaccess.egg-info/SOURCES.txt
+src/toolaccess.egg-info/dependency_links.txt
+src/toolaccess.egg-info/requires.txt
+src/toolaccess.egg-info/top_level.txt
+tests/test_toolaccess.py

toolaccess-0.1.0/src/toolaccess.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

toolaccess-0.1.0/src/toolaccess.egg-info/requires.txt

@@ -0,0 +1,9 @@
+fastapi
+fastmcp
+pydantic
+typer
+uvicorn
+
+[dev]
+pytest
+pytest-asyncio

toolaccess-0.1.0/src/toolaccess.egg-info/top_level.txt

@@ -0,0 +1 @@
+toolaccess

toolaccess-0.1.0/tests/test_toolaccess.py

@@ -0,0 +1,232 @@
+import pytest
+from fastapi.testclient import TestClient
+from typer.testing import CliRunner
+from toolaccess import (
+    ServerManager,
+    ToolService,
+    ToolDefinition,
+    OpenAPIServer,
+    SSEMCPServer,
+    CLIServer,
+)
+from contextlib import asynccontextmanager
+
+
+def dummy_tool(a: int, b: int) -> int:
+    """A dummy tool that adds two numbers."""
+    return a + b
+
+
+def dummy_admin():
+    """A dummy admin function."""
+    return {"status": "admin_ok"}
+
+
+@pytest.fixture
+def manager():
+    mgr = ServerManager(name="test_service")
+
+    # Services
+    tool_svc = ToolService("tools", [ToolDefinition(dummy_tool, "add_dummy", "POST")])
+    admin_svc = ToolService(
+        "admin", [ToolDefinition(dummy_admin, "check_admin", "GET")]
+    )
+
+    # 1. API v1
+    api_v1 = OpenAPIServer("/tools", "Tools API")
+    api_v1.mount(tool_svc)
+    mgr.add_server(api_v1)
+
+    # 2. Admin API
+    api_admin = OpenAPIServer("/admin", "Admin API")
+    api_admin.mount(admin_svc)
+    mgr.add_server(api_admin)
+
+    # 3. Default MCP
+    mcp = SSEMCPServer("default")
+    mcp.mount(tool_svc)
+    mgr.add_server(mcp)
+
+    # 4. Admin MCP
+    mcp_admin = SSEMCPServer("admin")
+    mcp_admin.mount(admin_svc)
+    mgr.add_server(mcp_admin)
+
+    # 5. CLI
+    cli_tools = CLIServer("tools")
+    cli_tools.mount(tool_svc)
+    mgr.add_server(cli_tools)
+
+    cli_admin = CLIServer("admin")
+    cli_admin.mount(admin_svc)
+    mgr.add_server(cli_admin)
+
+    return mgr
+
+
+@pytest.fixture
+def client(manager):
+    return TestClient(manager.app)
+
+
+@pytest.fixture
+def runner():
+    return CliRunner()
+
+
+def test_server_health(client):
+    """Test that the server health endpoint works."""
+    response = client.get("/health")
+    assert response.status_code == 200
+    data = response.json()
+    assert "mcp_servers" in data
+
+
+def test_tool_rest(client):
+    """Test accessing a tool via the mounted HTTP endpoint."""
+    response = client.post("/tools/add_dummy", params={"a": 1, "b": 2})
+    assert response.status_code == 200
+    assert response.json() == 3
+
+
+def test_admin_rest(client):
+    """Test accessing an admin function via the mounted HTTP endpoint."""
+    response = client.get("/admin/check_admin")
+    assert response.status_code == 200
+    assert response.json() == {"status": "admin_ok"}
+
+
+def test_mcp_endpoints(client):
+    """Test that MCP SSE endpoints are mounted."""
+    # Check default MCP server via messages endpoint (POST)
+    # FastMCP might redirect if slashes mismatch. Allow redirects.
+    # Note: If it redirects to a path without the prefix, that's a bug in the Dispatcher/SubApp interaction.
+    # We check for 404 specifically.
+
+    # Try with trailing slash to avoid 307 Redirect stripping the prefix
+    response = client.post("/mcp/default/messages/")
+    assert (
+        response.status_code != 404
+    ), f"Got {response.status_code}. History: {response.history}"
+
+    # Check admin MCP server
+    response = client.post("/mcp/admin/messages/")
+    assert response.status_code != 404
+
+
+def test_openapi_specs(client):
+    """Test that OpenAPI specs are generated for mounted sub-apps."""
+    # Check public tools spec - FastAPIMounts sub-apps don't always expose
+    # sub-openapi.json at the mount point automatically unless configured.
+    # However, our OpenAPIServer creates a full FastAPI app.
+    # When mounted, FastAPI serves the sub-app documentation at /tools/docs usually.
+    # The openapi.json is at /tools/openapi.json
+    response = client.get("/tools/openapi.json")
+    assert response.status_code == 200
+    spec = response.json()
+    assert "paths" in spec
+    assert "/add_dummy" in spec["paths"]
+
+    # Check admin spec
+    response = client.get("/admin/openapi.json")
+    assert response.status_code == 200
+    spec = response.json()
+    assert "/check_admin" in spec["paths"]
+
+
+def test_cli_integration(manager, runner):
+    """Test that registered tools appear in the CLI help."""
+    result = runner.invoke(manager.cli, ["tools", "--help"])
+    assert result.exit_code == 0
+    assert "add_dummy" in result.stdout
+
+    result = runner.invoke(manager.cli, ["admin", "--help"])
+    assert result.exit_code == 0
+    assert "check_admin" in result.stdout
+
+
+def test_async_cli_execution(runner):
+    """Test that async tools are correctly wrapped and executed in CLI."""
+    mgr = ServerManager("async_service")
+
+    async def async_tool(x: int) -> int:
+        return x * 2
+
+    # Service
+    svc = ToolService("svc", [ToolDefinition(async_tool, "double", "POST")])
+
+    # Server
+    cli = CLIServer("math")
+    cli.mount(svc)
+    mgr.add_server(cli)
+
+    result = runner.invoke(mgr.cli, ["math", "double", "21"])
+    assert result.exit_code == 0
+
+
+def test_lifespan_integration(runner):
+    """Test that lifespan context is entered during CLI execution."""
+    events = []
+
+    @asynccontextmanager
+    async def mock_lifespan(app):
+        events.append("startup")
+        yield
+        events.append("shutdown")
+
+    mgr = ServerManager(name="lifespan_service", lifespan=mock_lifespan)
+
+    async def simple_tool():
+        return "ok"
+
+    svc = ToolService("svc", [ToolDefinition(simple_tool, "simple_tool", "POST")])
+    cli = CLIServer("tools")
+    cli.mount(svc)
+    mgr.add_server(cli)
+
+    result = runner.invoke(mgr.cli, ["tools", "simple_tool"])
+    assert result.exit_code == 0
+    assert "startup" in events
+    assert "shutdown" in events
+
+
+def test_mcp_run_cli(manager, runner):
+    """Minimal test to ensure mcp-run command exists and doesn't crash on invocation."""
+    result = runner.invoke(manager.cli, ["mcp-run", "--name", "non_existent"])
+    assert result.exit_code == 0
+    assert "not found" in result.stdout
+
+
+def test_dynamic_server_lifecycle_explicit():
+    """Explicit test of dynamic add/remove."""
+    mgr = ServerManager("dynamic_test")
+    client = TestClient(mgr.app)
+
+    # 1. Verify 404 for non-existent path
+    response = client.get("/dynamic/openapi.json")
+    assert response.status_code == 404
+
+    # 2. Add Server
+    dynamic_api = OpenAPIServer("/dynamic", "Dynamic API")
+    dynamic_svc = ToolService(
+        "dynamic", [ToolDefinition(dummy_tool, "add_dynamic", "POST")]
+    )
+    dynamic_api.mount(dynamic_svc)
+
+    mgr.add_server(dynamic_api)
+
+    # 3. Verify 200 (It works!)
+    response = client.get("/dynamic/openapi.json")
+    assert response.status_code == 200
+
+    # Verify tool execution
+    response = client.post("/dynamic/add_dynamic", params={"a": 10, "b": 20})
+    assert response.status_code == 200
+    assert response.json() == 30
+
+    # 4. Remove Server
+    mgr.remove_server(dynamic_api)
+
+    # 5. Verify 404 again
+    response = client.get("/dynamic/openapi.json")
+    assert response.status_code == 404