py2mcp 0.1.1__py3-none-any.whl

py2mcp/__init__.py

@@ -0,0 +1,27 @@
+"""py2mcp: Quick MCP server creation from Python functions.
+
+This package provides a simple, Pythonic way to create Model Context Protocol (MCP)
+servers from ordinary Python functions. Built on FastMCP, it handles all the protocol
+complexity while letting you focus on your business logic.
+
+Basic usage:
+    >>> from py2mcp import mk_mcp_server
+    >>>
+    >>> def add(a: int, b: int) -> int:
+    ...     '''Add two numbers'''
+    ...     return a + b
+    >>>
+    >>> mcp = mk_mcp_server([add])
+    >>> # mcp.run()  # Start the server
+"""
+
+from py2mcp.main import mk_mcp_server, mk_mcp_from_store
+from py2mcp.trans import mk_input_trans
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "mk_mcp_server",
+    "mk_mcp_from_store",
+    "mk_input_trans",
+]

py2mcp/base.py

@@ -0,0 +1,49 @@
+"""Base objects and utilities for py2mcp."""
+
+from typing import Callable, Iterable, Any, Optional
+from functools import wraps
+
+
+def _wrap_with_input_trans(func: Callable, input_trans: Optional[Callable]) -> Callable:
+    """Wrap a function to apply input transformation.
+
+    >>> def double(x): return x * 2
+    >>> def add_one_trans(kwargs): return {k: v + 1 for k, v in kwargs.items()}
+    >>> wrapped = _wrap_with_input_trans(double, add_one_trans)
+    >>> wrapped(x=5)
+    12
+    """
+    if input_trans is None:
+        return func
+
+    @wraps(func)
+    def wrapper(**kwargs):
+        transformed = input_trans(kwargs)
+        return func(**transformed)
+
+    # Preserve original function metadata for introspection
+    wrapper.__wrapped__ = func
+    return wrapper
+
+
+def _normalize_to_iterable(funcs: Any) -> Iterable[Callable]:
+    """Normalize input to an iterable of callables.
+
+    >>> def f(): pass
+    >>> def g(): pass
+    >>> list(_normalize_to_iterable(f))
+    [<function f at ...>]
+    >>> len(list(_normalize_to_iterable([f, g])))
+    2
+    """
+    if callable(funcs):
+        return [funcs]
+    elif isinstance(funcs, Iterable):
+        result = list(funcs)
+        if not all(callable(f) for f in result):
+            raise TypeError("All items must be callable")
+        return result
+    else:
+        raise TypeError(
+            f"Expected callable or iterable of callables, got {type(funcs)}"
+        )

py2mcp/main.py

@@ -0,0 +1,91 @@
+"""Main entry point for creating MCP servers from Python functions."""
+
+from typing import Callable, Iterable, Optional, MutableMapping, Any
+from fastmcp import FastMCP
+
+from py2mcp.base import _normalize_to_iterable, _wrap_with_input_trans
+from py2mcp.util import store_to_funcs
+
+
+def mk_mcp_server(
+    funcs: Callable | Iterable[Callable],
+    *,
+    name: str = "py2mcp Server",
+    input_trans: Optional[Callable[[dict], dict]] = None,
+) -> FastMCP:
+    """Create an MCP server from Python functions.
+
+    This is the main entry point for py2mcp. Pass one or more functions,
+    and get back a FastMCP server ready to run.
+
+    Args:
+        funcs: A function or iterable of functions to expose as MCP tools
+        name: Name of the MCP server
+        input_trans: Optional function to transform input kwargs before calling tools
+
+    Returns:
+        A FastMCP server instance ready to run
+
+    Examples:
+        >>> def add(a: int, b: int) -> int:
+        ...     '''Add two numbers'''
+        ...     return a + b
+        >>> mcp = mk_mcp_server(add)
+        >>> mcp.name
+        'py2mcp Server'
+
+        >>> def greet(name: str) -> str:
+        ...     return f"Hello, {name}!"
+        >>> mcp = mk_mcp_server([add, greet], name="Math & Greetings")
+        >>> mcp.name
+        'Math & Greetings'
+    """
+    mcp = FastMCP(name)
+
+    # Normalize to list of functions
+    func_list = list(_normalize_to_iterable(funcs))
+
+    # Register each function as a tool
+    for func in func_list:
+        # Wrap with input transformation if provided
+        if input_trans is not None:
+            func = _wrap_with_input_trans(func, input_trans)
+
+        # Register as MCP tool
+        mcp.tool(func)
+
+    return mcp
+
+
+def mk_mcp_from_store(
+    store: MutableMapping[Any, Any],
+    *,
+    name: str = "item",
+    plural: str = "",
+    server_name: Optional[str] = None,
+) -> FastMCP:
+    """Create an MCP server from a MutableMapping with CRUD operations.
+
+    Automatically generates list, get, set, and delete functions for the store.
+
+    Args:
+        store: A MutableMapping to expose via MCP
+        name: Singular name for items (e.g., 'project', 'user')
+        plural: Plural form (defaults to name + 's')
+        server_name: Name of the MCP server (defaults to "{name} Store")
+
+    Returns:
+        A FastMCP server with CRUD operations
+
+    Examples:
+        >>> projects = {'p1': {'name': 'Project 1'}, 'p2': {'name': 'Project 2'}}
+        >>> mcp = mk_mcp_from_store(projects, name='project')
+        >>> mcp.name
+        'project Store'
+    """
+    if server_name is None:
+        server_name = f"{name} Store"
+
+    funcs = store_to_funcs(store, name=name, plural=plural)
+
+    return mk_mcp_server(funcs, name=server_name)

py2mcp/tests/test_basic.py

@@ -0,0 +1,241 @@
+"""Tests for py2mcp functionality."""
+
+import pytest
+import asyncio
+
+from py2mcp import mk_mcp_server, mk_mcp_from_store, mk_input_trans
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _run(coro):
+    """Run a coroutine synchronously."""
+    return asyncio.run(coro)
+
+
+def _call(mcp, tool_name, args=None):
+    """Call a tool on an MCP server and return the structured result."""
+    result = _run(mcp.call_tool(tool_name, args or {}))
+    return result.structured_content.get('result', result.structured_content)
+
+
+# ---------------------------------------------------------------------------
+# Unit tests
+# ---------------------------------------------------------------------------
+
+
+def test_single_function():
+    """Test creating an MCP server from a single function."""
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    mcp = mk_mcp_server(add)
+    assert mcp is not None
+    assert mcp.name == "py2mcp Server"
+
+
+def test_multiple_functions():
+    """Test creating an MCP server from multiple functions."""
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    def multiply(a: int, b: int) -> int:
+        return a * b
+
+    mcp = mk_mcp_server([add, multiply], name="Math Server")
+    assert mcp.name == "Math Server"
+
+
+def test_input_transformation():
+    """Test input transformation."""
+    trans = mk_input_trans({'x': int, 'y': float})
+
+    result = trans({'x': '42', 'y': '3.14', 'z': 'unchanged'})
+    assert result['x'] == 42
+    assert result['y'] == 3.14
+    assert result['z'] == 'unchanged'
+
+
+def test_input_trans_with_none():
+    """Test that None input_trans works correctly."""
+    trans = mk_input_trans(None)
+
+    result = trans({'a': 1, 'b': 2})
+    assert result == {'a': 1, 'b': 2}
+
+
+def test_store_to_mcp():
+    """Test creating MCP server from a store."""
+    store = {'item1': 'value1', 'item2': 'value2'}
+
+    mcp = mk_mcp_from_store(store, name='item')
+    assert mcp.name == 'item Store'
+
+
+def test_store_operations():
+    """Test that store operations work correctly."""
+    from py2mcp.util import store_to_funcs
+
+    store = {'a': 1, 'b': 2}
+    funcs = store_to_funcs(store, name='item')
+
+    assert len(funcs) == 4
+
+    func_names = [f.__name__ for f in funcs]
+    assert 'list_items' in func_names
+    assert 'get_item' in func_names
+    assert 'set_item' in func_names
+    assert 'delete_item' in func_names
+
+
+def test_store_list_operation():
+    """Test list operation on store."""
+    from py2mcp.util import store_to_funcs
+
+    store = {'a': 1, 'b': 2, 'c': 3}
+    funcs = {f.__name__: f for f in store_to_funcs(store, name='item')}
+
+    items = funcs['list_items']()
+    assert set(items) == {'a', 'b', 'c'}
+
+
+def test_store_get_operation():
+    """Test get operation on store."""
+    from py2mcp.util import store_to_funcs
+
+    store = {'x': 100, 'y': 200}
+    funcs = {f.__name__: f for f in store_to_funcs(store, name='item')}
+
+    assert funcs['get_item']('x') == 100
+    assert funcs['get_item']('y') == 200
+
+
+def test_store_set_operation():
+    """Test set operation on store."""
+    from py2mcp.util import store_to_funcs
+
+    store = {}
+    funcs = {f.__name__: f for f in store_to_funcs(store, name='item')}
+
+    funcs['set_item']('new_key', 'new_value')
+    assert store['new_key'] == 'new_value'
+
+
+def test_store_delete_operation():
+    """Test delete operation on store."""
+    from py2mcp.util import store_to_funcs
+
+    store = {'to_delete': 'value'}
+    funcs = {f.__name__: f for f in store_to_funcs(store, name='item')}
+
+    funcs['delete_item']('to_delete')
+    assert 'to_delete' not in store
+
+
+def test_store_custom_plural():
+    """Test store functions with custom plural form."""
+    from py2mcp.util import store_to_funcs
+
+    store = {'a': 1}
+    funcs = store_to_funcs(store, name='cactus', plural='cacti')
+    func_names = [f.__name__ for f in funcs]
+    assert func_names == ['list_cacti', 'get_cactus', 'set_cactus', 'delete_cactus']
+
+
+def test_invalid_input():
+    """Test that invalid inputs raise appropriate errors."""
+    with pytest.raises(TypeError):
+        mk_mcp_server("not a function")
+
+    with pytest.raises(TypeError):
+        mk_mcp_server([lambda x: x, "not a function"])
+
+
+# ---------------------------------------------------------------------------
+# End-to-end tests (calling tools through the MCP server)
+# ---------------------------------------------------------------------------
+
+
+def test_e2e_call_tool():
+    """End-to-end: call a tool through the MCP server."""
+    def add(a: int, b: int) -> int:
+        """Add two numbers."""
+        return a + b
+
+    mcp = mk_mcp_server(add)
+    assert _call(mcp, 'add', {'a': 3, 'b': 4}) == 7
+
+
+def test_e2e_multiple_tools():
+    """End-to-end: register and call multiple tools."""
+    def add(a: int, b: int) -> int:
+        """Add."""
+        return a + b
+
+    def multiply(a: int, b: int) -> int:
+        """Multiply."""
+        return a * b
+
+    mcp = mk_mcp_server([add, multiply])
+
+    assert _call(mcp, 'add', {'a': 2, 'b': 3}) == 5
+    assert _call(mcp, 'multiply', {'a': 2, 'b': 3}) == 6
+
+
+def test_e2e_list_tools():
+    """End-to-end: list registered tools."""
+    def greet(name: str) -> str:
+        """Greet someone."""
+        return f"Hello, {name}!"
+
+    def farewell(name: str) -> str:
+        """Say goodbye."""
+        return f"Goodbye, {name}!"
+
+    mcp = mk_mcp_server([greet, farewell])
+    tools = _run(mcp.list_tools())
+    tool_names = {t.name for t in tools}
+    assert tool_names == {'greet', 'farewell'}
+
+
+def test_e2e_store_crud():
+    """End-to-end: full CRUD cycle through the MCP server."""
+    store = {'a': 1, 'b': 2}
+    mcp = mk_mcp_from_store(store, name='item')
+
+    # List
+    keys = _call(mcp, 'list_items')
+    assert set(keys) == {'a', 'b'}
+
+    # Get
+    assert _call(mcp, 'get_item', {'key': 'a'}) == 1
+
+    # Set
+    _call(mcp, 'set_item', {'key': 'c', 'value': 3})
+    assert store['c'] == 3
+
+    # Delete
+    _call(mcp, 'delete_item', {'key': 'a'})
+    assert 'a' not in store
+
+    # List after mutations
+    keys = _call(mcp, 'list_items')
+    assert set(keys) == {'b', 'c'}
+
+
+def test_e2e_input_trans():
+    """End-to-end: input transformation through the MCP server."""
+    def compute(x: int, y: int) -> int:
+        """Compute x + y after transformation."""
+        return x + y
+
+    trans = mk_input_trans({'x': lambda v: v * 10})
+    mcp = mk_mcp_server(compute, input_trans=trans)
+
+    assert _call(mcp, 'compute', {'x': 3, 'y': 1}) == 31
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])

py2mcp/trans.py

@@ -0,0 +1,105 @@
+"""Input and output transformation utilities for py2mcp."""
+
+from typing import Callable, Mapping, Iterable, Optional, Iterator
+
+
+def _name_func_pairs_from_mapping(
+    name_func_relationships: Mapping,
+) -> Iterator[tuple[str, Callable]]:
+    """Generate (name, func) pairs from various mapping formats.
+
+    Supports:
+    - {name: func} - standard mapping
+    - {name: [func1, func2]} - one name, multiple functions
+    - {func: name} - reversed mapping
+    - {func: [name1, name2]} - one function, multiple names
+
+    >>> def double(x): return x * 2
+    >>> list(_name_func_pairs_from_mapping({'x': double}))
+    [('x', <function double at ...>)]
+    """
+    for k, v in name_func_relationships.items():
+        if isinstance(k, str):
+            name = k
+            if callable(v):
+                yield name, v
+            elif isinstance(v, Iterable):
+                for func in v:
+                    if not callable(func):
+                        raise TypeError(f"Expected callable, got {type(func)}")
+                    yield name, func
+            else:
+                raise TypeError(f"Value must be callable or iterable of callables: {v}")
+        elif callable(k):
+            func = k
+            if isinstance(v, str):
+                yield v, func
+            elif isinstance(v, Iterable):
+                for name in v:
+                    if not isinstance(name, str):
+                        raise TypeError(f"Expected string, got {type(name)}")
+                    yield name, func
+            else:
+                raise TypeError(f"Value must be string or iterable of strings: {v}")
+        else:
+            raise TypeError(f"Key must be string or callable: {k}")
+
+
+def _to_name_func_map(name_func_relationships: Mapping) -> dict[str, Callable]:
+    """Convert name-func relationships to a simple name->func mapping.
+
+    >>> def double(x): return x * 2
+    >>> _to_name_func_map({'x': double})
+    {'x': <function double at ...>}
+    """
+    if not isinstance(name_func_relationships, Mapping):
+        raise TypeError(
+            f"Expected Mapping of name:func or func:name pairs, got {type(name_func_relationships)}"
+        )
+
+    pairs = list(_name_func_pairs_from_mapping(name_func_relationships))
+    result = dict(pairs)
+
+    if len(result) != len(pairs):
+        raise ValueError("Duplicate names found in relationships")
+
+    return result
+
+
+def _apply_transformations(
+    kwargs: dict, name_func_map: Mapping[str, Callable]
+) -> Iterator[tuple[str, any]]:
+    """Apply transformations to matching kwargs.
+
+    >>> def double(x): return x * 2
+    >>> transforms = {'a': double}
+    >>> dict(_apply_transformations({'a': 5, 'b': 10}, transforms))
+    {'a': 10, 'b': 10}
+    """
+    for name, value in kwargs.items():
+        if name in name_func_map:
+            yield name, name_func_map[name](value)
+        else:
+            yield name, value
+
+
+def mk_input_trans(
+    name_func_relationships: Optional[Mapping] = None,
+) -> Callable[[dict], dict]:
+    """Create an input transformation function from name->func mappings.
+
+    >>> def to_int(x): return int(x)
+    >>> trans = mk_input_trans({'x': to_int})
+    >>> trans({'x': '42', 'y': 'hello'})
+    {'x': 42, 'y': 'hello'}
+    """
+    if name_func_relationships is None:
+        return lambda kwargs: dict(kwargs)
+
+    name_func_map = _to_name_func_map(name_func_relationships)
+
+    def input_trans(kwargs: dict) -> dict:
+        """Transform input kwargs according to the mapping."""
+        return dict(_apply_transformations(kwargs, name_func_map))
+
+    return input_trans

py2mcp/util.py

@@ -0,0 +1,70 @@
+"""General utilities for py2mcp."""
+
+from typing import MutableMapping, Callable, TypeVar
+from collections.abc import Iterator
+
+KT = TypeVar("KT")
+VT = TypeVar("VT")
+
+
+def _store_to_funcs(
+    store: MutableMapping[KT, VT],
+    *,
+    singular: str = "item",
+    plural: str = "",
+) -> Iterator[tuple[str, Callable]]:
+    """Generate CRUD functions from a MutableMapping.
+
+    >>> store = {'a': 1, 'b': 2}
+    >>> funcs = dict(_store_to_funcs(store, singular='item'))
+    >>> sorted(funcs['list_items']())
+    ['a', 'b']
+    >>> funcs['get_item']('a')
+    1
+    """
+    plural = plural or f"{singular}s"
+
+    def list_items() -> list[KT]:
+        """List all keys."""
+        return list(store.keys())
+
+    def get_item(key: KT) -> VT:
+        """Get a value by key."""
+        return store[key]
+
+    def set_item(key: KT, value: VT) -> str:
+        """Set a value."""
+        store[key] = value
+        return f"Set {singular} '{key}'"
+
+    def delete_item(key: KT) -> str:
+        """Delete a value."""
+        del store[key]
+        return f"Deleted {singular} '{key}'"
+
+    for func, func_name in [
+        (list_items, f"list_{plural}"),
+        (get_item, f"get_{singular}"),
+        (set_item, f"set_{singular}"),
+        (delete_item, f"delete_{singular}"),
+    ]:
+        func.__name__ = func_name
+        yield func_name, func
+
+
+def store_to_funcs(
+    store: MutableMapping[KT, VT],
+    *,
+    name: str = "item",
+    plural: str = "",
+) -> list[Callable]:
+    """Convert a MutableMapping into CRUD functions.
+
+    >>> projects = {'p1': {'name': 'Project 1'}}
+    >>> funcs = store_to_funcs(projects, name='project')
+    >>> len(funcs)
+    4
+    >>> [f.__name__ for f in funcs]
+    ['list_projects', 'get_project', 'set_project', 'delete_project']
+    """
+    return [func for _, func in _store_to_funcs(store, singular=name, plural=plural)]

py2mcp-0.1.1.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: py2mcp
+Version: 0.1.1
+Summary: Quick MCP server creation from Python functions
+Project-URL: Homepage, https://github.com/i2mint/py2mcp
+Project-URL: Repository, https://github.com/i2mint/py2mcp
+Project-URL: Documentation, https://i2mint.github.io/py2mcp
+Author: Thor Whalen
+License: mit
+License-File: LICENSE
+Keywords: ai,llm,mcp,model-context-protocol
+Requires-Python: >=3.10
+Requires-Dist: fastmcp
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# py2mcp
+
+Quick MCP (Model Context Protocol) server creation from Python functions.
+
+## Installation
+
+```bash
+pip install py2mcp
+```
+
+## Quick Start
+
+```python
+from py2mcp import mk_mcp_server
+
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+def greet(name: str = "world") -> str:
+    """Greet someone"""
+    return f"Hello, {name}!"
+
+# Create and run MCP server
+mcp = mk_mcp_server([add, greet])
+
+if __name__ == '__main__':
+    mcp.run()
+```
+
+That's it! Your functions are now available as MCP tools.
+
+## Features
+
+- **Simple**: Just pass functions to `mk_mcp_server()`
+- **Flexible**: Supports input/output transformations
+- **Pythonic**: Clean, decorator-free function definitions
+- **Powerful**: Built on FastMCP for production-ready servers
+
+## Input Transformations
+
+Transform inputs before they reach your functions:
+
+```python
+from py2mcp import mk_mcp_server, mk_input_trans
+import numpy as np
+
+def add_arrays(a, b):
+    """Add two numpy arrays"""
+    return (a + b).tolist()
+
+# Convert list inputs to numpy arrays
+input_trans = mk_input_trans({'a': np.array, 'b': np.array})
+mcp = mk_mcp_server([add_arrays], input_trans=input_trans)
+```
+
+## From Stores (MutableMapping)
+
+Automatically expose CRUD operations from any mapping:
+
+```python
+from py2mcp import mk_mcp_from_store
+
+projects = {'proj1': {'name': 'Project 1'}, 'proj2': {'name': 'Project 2'}}
+mcp = mk_mcp_from_store(projects, name="project")
+
+# Automatically creates: list_projects, get_project, set_project, delete_project
+```
+
+## License
+
+MIT

py2mcp-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+py2mcp/__init__.py,sha256=O6zE924L-4RGq00DxbVaXVXMn7l7eITQfkTLTM41Dj0,743
+py2mcp/base.py,sha256=uFYe9dN-2Yr0MRV2Dzv0sT3M5awUwPhRoXA_SYwdpLg,1426
+py2mcp/main.py,sha256=ZYjZWZhRFkvtZjwOxVda07GuXKkc7Qg742nH76tTSrE,2739
+py2mcp/trans.py,sha256=pj53X58DIE2ToaY2z3ZM6673d53kEAI-YfTsvs6BOFE,3571
+py2mcp/util.py,sha256=VNk_akypXYH3FqVVuxFEG897KyjQOnxoXZtQ4iflmf8,1853
+py2mcp/tests/test_basic.py,sha256=F-bVB-VLXPYlVC557Yocmkm009yA_6Ol5_T3NUUNw0U,6642
+py2mcp-0.1.1.dist-info/METADATA,sha256=5fvf_4AxUvW1QXRehHERbXTq9MpJoKq9Cq22XblXHTM,2283
+py2mcp-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+py2mcp-0.1.1.dist-info/licenses/LICENSE,sha256=ekE13yCE9fWWEJfP1NPnUJabZ_Wwrc6coKJV2ZZx27w,1068
+py2mcp-0.1.1.dist-info/RECORD,,

py2mcp-0.1.1.dist-info/WHEEL

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

py2mcp-0.1.1.dist-info/licenses/LICENSE

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