py2mcp 0.1.1__tar.gz

py2mcp-0.1.1/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

py2mcp-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,256 @@
+name: Continuous Integration (uv)
+on: [push, pull_request]
+
+# Note: Environment variables (PROJECT_NAME and vars from [tool.wads.ci.env])
+# are set by the read-ci-config action in the setup job and made available
+# to all subsequent jobs via GITHUB_ENV
+
+jobs:
+  # First job: Read configuration from pyproject.toml
+  setup:
+    name: Read Configuration
+    runs-on: ubuntu-latest
+    outputs:
+      project-name: ${{ steps.config.outputs.project-name }}
+      python-versions: ${{ steps.config.outputs.python-versions }}
+      pytest-args: ${{ steps.config.outputs.pytest-args }}
+      coverage-enabled: ${{ steps.config.outputs.coverage-enabled }}
+      exclude-paths: ${{ steps.config.outputs.exclude-paths }}
+      test-on-windows: ${{ steps.config.outputs.test-on-windows }}
+      build-sdist: ${{ steps.config.outputs.build-sdist }}
+      build-wheel: ${{ steps.config.outputs.build-wheel }}
+      metrics-enabled: ${{ steps.config.outputs.metrics-enabled }}
+      metrics-config-path: ${{ steps.config.outputs.metrics-config-path }}
+      metrics-storage-branch: ${{ steps.config.outputs.metrics-storage-branch }}
+      metrics-python-version: ${{ steps.config.outputs.metrics-python-version }}
+      metrics-force-run: ${{ steps.config.outputs.metrics-force-run }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Read CI Config
+        id: config
+        uses: i2mint/wads/actions/read-ci-config@master
+        with:
+          pyproject-path: .
+
+  # Second job: Validation using the config
+  validation:
+    name: Validation
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    needs: setup
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ${{ fromJson(needs.setup.outputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: |
+          uv python install ${{ matrix.python-version }}
+          uv venv --python ${{ matrix.python-version }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        run: |
+          source .venv/bin/activate
+          uv pip install -e ".[dev]"
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Lint Validation
+        run: uvx ruff check --output-format=github ${{ needs.setup.outputs.project-name }}
+
+      - name: Run Tests
+        run: |
+          source .venv/bin/activate
+          PYTEST_ARGS="${{ needs.setup.outputs.pytest-args }}"
+          EXCLUDE="${{ needs.setup.outputs.exclude-paths }}"
+          COVERAGE="${{ needs.setup.outputs.coverage-enabled }}"
+          ROOT_DIR="${{ needs.setup.outputs.project-name }}"
+
+          CMD="python -m pytest"
+
+          # Add coverage flags
+          if [ "$COVERAGE" = "true" ]; then
+            uv pip install pytest-cov
+            CMD="$CMD --cov=$ROOT_DIR --cov-report=term-missing"
+          fi
+
+          # Add doctest flags
+          CMD="$CMD --doctest-modules"
+          CMD="$CMD -o doctest_optionflags='ELLIPSIS IGNORE_EXCEPTION_DETAIL'"
+
+          # Add exclude paths
+          if [ -n "$EXCLUDE" ]; then
+            IFS=',' read -ra PATHS <<< "$EXCLUDE"
+            for path in "${PATHS[@]}"; do
+              path=$(echo "$path" | xargs)
+              CMD="$CMD --ignore=$path"
+            done
+          fi
+
+          # Add extra pytest args
+          if [ -n "$PYTEST_ARGS" ]; then
+            CMD="$CMD $PYTEST_ARGS"
+          fi
+
+          echo "Running: $CMD"
+          eval $CMD
+
+      - name: Track Code Metrics
+        if: needs.setup.outputs.metrics-enabled == 'true'
+        uses: i2mint/umpyre/actions/track-metrics@master
+        continue-on-error: true
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: ${{ needs.setup.outputs.metrics-config-path }}
+          storage-branch: ${{ needs.setup.outputs.metrics-storage-branch }}
+          python-version: ${{ needs.setup.outputs.metrics-python-version }}
+          force-run: ${{ needs.setup.outputs.metrics-force-run }}
+
+  # Optional Windows testing (if enabled in config)
+  windows-validation:
+    name: Windows Tests
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && needs.setup.outputs.test-on-windows == 'true'"
+    needs: setup
+    runs-on: windows-latest
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: |
+          uv python install ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+          uv venv
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        run: |
+          .venv\Scripts\activate
+          uv pip install -e ".[dev]"
+
+      - name: Run tests
+        id: test
+        continue-on-error: true
+        run: |
+          .venv\Scripts\activate
+          pytest
+
+      - name: Report test results
+        if: always()
+        run: |
+          if ("${{ steps.test.outcome }}" -eq "failure") {
+            echo "::warning::Windows tests failed but workflow continues"
+            echo "## ⚠️ Windows Tests Failed" >> $env:GITHUB_STEP_SUMMARY
+            echo "Tests failed on Windows but this is informational only." >> $env:GITHUB_STEP_SUMMARY
+          } else {
+            echo "## ✅ Windows Tests Passed" >> $env:GITHUB_STEP_SUMMARY
+          }
+
+  # Publishing job
+  publish:
+    name: Publish
+    permissions:
+      contents: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')"
+    needs: [setup, validation]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+
+      - name: Format Source Code
+        run: uvx ruff format .
+
+      - name: Update Version Number
+        id: version
+        uses: i2mint/isee/actions/bump-version-number@master
+
+      - name: Build Distribution
+        run: |
+          BUILD_ARGS=""
+          if [ "${{ needs.setup.outputs.build-sdist }}" = "false" ]; then
+            BUILD_ARGS="$BUILD_ARGS --no-sdist"
+          fi
+          if [ "${{ needs.setup.outputs.build-wheel }}" = "false" ]; then
+            BUILD_ARGS="$BUILD_ARGS --no-wheel"
+          fi
+          uv build $BUILD_ARGS
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_PASSWORD }}
+        run: uv publish dist/*
+
+      - name: Force SSH for git remote
+        run: |
+          git remote set-url origin git@github.com:${{ github.repository }}.git
+
+      - name: Commit Changes
+        uses: i2mint/wads/actions/git-commit@master
+        with:
+          commit-message: "**CI** Formatted code + Updated version to ${{ env.VERSION }} [skip ci]"
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+          push: true
+
+      - name: Tag Repository
+        uses: i2mint/wads/actions/git-tag@master
+        with:
+          tag: ${{ env.VERSION }}
+          message: "Release version ${{ env.VERSION }}"
+          push: true
+
+  # Optional GitHub Pages
+  github-pages:
+    name: Publish GitHub Pages
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)"
+    needs: publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: i2mint/epythet/actions/publish-github-pages@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          ignore: "tests/,scrap/,examples/"

py2mcp-0.1.1/.gitignore

@@ -0,0 +1,121 @@
+wads_configs.json
+data/wads_configs.json
+wads/data/wads_configs.json
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

py2mcp-0.1.1/COMPARISON.md

@@ -0,0 +1,346 @@
+# py2mcp vs qh (py2http) - Pattern Comparison
+
+This document shows how `py2mcp` follows the same design patterns as `qh` (the HTTP service builder), making it familiar and intuitive.
+
+## Core Pattern: Functions → Server
+
+### qh (HTTP)
+```python
+from qh import mk_http_service_app
+
+def add(a: int, b: int) -> int:
+    return a + b
+
+app = mk_http_service_app([add])
+app.run()
+```
+
+### py2mcp (MCP)
+```python
+from py2mcp import mk_mcp_server
+
+def add(a: int, b: int) -> int:
+    return a + b
+
+mcp = mk_mcp_server([add])
+mcp.run()
+```
+
+**Identical pattern!** Pass functions, get a server.
+
+## Input Transformations
+
+### qh (HTTP)
+```python
+from qh import mk_http_service_app
+from qh.trans import mk_json_handler_from_name_mapping
+import numpy as np
+
+def add_arrays(a, b):
+    return (a + b).tolist()
+
+input_trans = mk_json_handler_from_name_mapping({
+    'a': np.array,
+    'b': np.array
+})
+
+app = mk_http_service_app([add_arrays], input_trans=input_trans)
+```
+
+### py2mcp (MCP)
+```python
+from py2mcp import mk_mcp_server, mk_input_trans
+import numpy as np
+
+def add_arrays(a, b):
+    return (a + b).tolist()
+
+input_trans = mk_input_trans({
+    'a': np.array,
+    'b': np.array
+})
+
+mcp = mk_mcp_server([add_arrays], input_trans=input_trans)
+```
+
+**Same transformation pattern!** Map parameter names to conversion functions.
+
+## Store/Mapping Dispatch
+
+### qh (HTTP) - Conceptual
+```python
+# qh has store dispatch patterns (see scrap/store_dispatch_*.py)
+# where a MutableMapping is exposed via HTTP endpoints
+
+from qh.scrap.store_dispatch_1 import StoreAccess
+
+store = StoreAccess.from_uri('test_uri')
+# Exposes: list(), read(), write(), delete()
+```
+
+### py2mcp (MCP)
+```python
+from py2mcp import mk_mcp_from_store
+
+projects = {'proj1': {...}, 'proj2': {...}}
+
+mcp = mk_mcp_from_store(projects, name='project')
+# Automatically creates:
+# - list_projects()
+# - get_project(key)
+# - set_project(key, value)
+# - delete_project(key)
+```
+
+**Same CRUD pattern!** Automatically generate operations from stores.
+
+## Architecture Parallels
+
+| Aspect | qh (py2http) | py2mcp |
+|--------|--------------|---------|
+| **Foundation** | py2http (bottle/FastAPI) | FastMCP |
+| **Philosophy** | Don't reinvent HTTP | Don't reinvent MCP |
+| **Main Function** | `mk_http_service_app()` | `mk_mcp_server()` |
+| **Transformation** | `mk_json_handler_from_name_mapping()` | `mk_input_trans()` |
+| **Store Support** | Store dispatch examples | `mk_mcp_from_store()` |
+| **Return Type** | HTTP app object | FastMCP object |
+| **Run Method** | `app.run()` | `mcp.run()` |
+
+## Module Structure Comparison
+
+### qh Structure
+```
+qh/
+├── __init__.py          # Exports: mk_http_service_app
+├── main.py              # Core app creation
+├── trans.py             # Transformations
+├── util.py              # Helpers (flat_callable_for, etc.)
+└── scrap/               # WIP patterns
+```
+
+### py2mcp Structure
+```
+py2mcp/
+├── __init__.py          # Exports: mk_mcp_server, mk_input_trans, mk_mcp_from_store
+├── main.py              # Core server creation
+├── trans.py             # Transformations
+├── util.py              # Helpers (store_to_funcs, etc.)
+└── tests/               # Test suite
+```
+
+**Nearly identical organization!**
+
+## Implementation Details
+
+### Function Flattening
+
+Both packages handle methods and functions uniformly:
+
+#### qh
+```python
+# from qh.util import flat_callable_for
+def flat_callable_for(func, func_name=None, cls=None):
+    """Flatten cls->instance->method call pipeline"""
+    containing_cls = get_class_that_defined_method(func)
+    if not containing_cls:
+        return func  # Already flat
+    # ... flatten the method
+```
+
+#### py2mcp
+```python
+# from py2mcp.base import _normalize_to_iterable
+def _normalize_to_iterable(funcs):
+    """Normalize input to an iterable of callables"""
+    if callable(funcs):
+        return [funcs]
+    elif isinstance(funcs, Iterable):
+        return list(funcs)
+    # ... validate
+```
+
+### Transformation Pipeline
+
+Both use the same pattern: **name → function mapping**
+
+#### qh
+```python
+def transform_mapping_vals_with_name_func_map(mapping, name_func_map):
+    for name, val in mapping.items():
+        if name in name_func_map:
+            yield name, name_func_map[name](val)
+        else:
+            yield name, val
+```
+
+#### py2mcp
+```python
+def _apply_transformations(kwargs, name_func_map):
+    for name, value in kwargs.items():
+        if name in name_func_map:
+            yield name, name_func_map[name](value)
+        else:
+            yield name, value
+```
+
+**Identical logic!**
+
+## Key Differences
+
+While the patterns are the same, there are protocol differences:
+
+| Feature | HTTP (qh) | MCP (py2mcp) |
+|---------|-----------|--------------|
+| **Transport** | HTTP endpoints | Stdio/HTTP/SSE |
+| **Client** | curl, browsers | Claude, Cursor, MCP clients |
+| **Method Types** | GET/POST/PUT/DELETE | Tools/Resources/Prompts |
+| **Request Format** | JSON body, URL params | JSON-RPC |
+| **Response Format** | JSON response | Structured tool results |
+
+## Usage Comparison
+
+### Starting a Server
+
+#### qh
+```python
+# HTTP server on port 8080
+if __name__ == '__main__':
+    app.run(port=8080)
+```
+
+Test with:
+```bash
+curl -X POST http://localhost:8080/add \
+  -H "Content-Type: application/json" \
+  -d '{"a": 3, "b": 5}'
+```
+
+#### py2mcp
+```python
+# Stdio server (default) or HTTP
+if __name__ == '__main__':
+    mcp.run()  # stdio
+    # mcp.run(transport='http', port=8000)  # http
+```
+
+Test with:
+```bash
+fastmcp dev server.py  # Opens web inspector
+```
+
+### Function Requirements
+
+Both require:
+- Type hints (for schema generation)
+- Docstrings (for documentation)
+- JSON-serializable returns
+
+```python
+# Works in both qh and py2mcp
+def process_data(
+    text: str,
+    count: int = 10,
+    uppercase: bool = False
+) -> dict:
+    """Process text data.
+    
+    Args:
+        text: Input text
+        count: Max length
+        uppercase: Convert to uppercase
+    
+    Returns:
+        Processed result
+    """
+    result = text[:count]
+    if uppercase:
+        result = result.upper()
+    return {"result": result, "length": len(result)}
+```
+
+## Migration Guide: HTTP → MCP
+
+If you have a qh HTTP service and want to make it an MCP server:
+
+1. **Change import**:
+   ```python
+   # from qh import mk_http_service_app
+   from py2mcp import mk_mcp_server
+   ```
+
+2. **Change function name**:
+   ```python
+   # app = mk_http_service_app([...])
+   mcp = mk_mcp_server([...])
+   ```
+
+3. **Update transformations** (if used):
+   ```python
+   # from qh.trans import mk_json_handler_from_name_mapping
+   from py2mcp import mk_input_trans
+   
+   # input_trans = mk_json_handler_from_name_mapping({...})
+   input_trans = mk_input_trans({...})
+   ```
+
+4. **Change run call**:
+   ```python
+   # app.run(port=8080)
+   mcp.run()  # or mcp.run(transport='http', port=8000)
+   ```
+
+That's it! Your functions stay exactly the same.
+
+## When to Use Which?
+
+### Use qh (py2http) when:
+- You need HTTP/REST endpoints
+- Building a web API
+- Want browser/curl access
+- Integrating with HTTP clients
+
+### Use py2mcp when:
+- Building AI agent tools
+- Integrating with Claude/Cursor
+- Want LLM-friendly interfaces
+- Following MCP standard
+
+### Use both when:
+- You want both HTTP and MCP access
+- Maximum flexibility
+- Different client types
+
+```python
+from qh import mk_http_service_app
+from py2mcp import mk_mcp_server
+
+# Same functions, two servers!
+funcs = [add, multiply, greet]
+
+http_app = mk_http_service_app(funcs)
+mcp_server = mk_mcp_server(funcs)
+```
+
+## Design Philosophy
+
+Both packages follow the same principles:
+
+1. **Simplicity**: Minimal API surface
+2. **Convention over configuration**: Sensible defaults
+3. **Don't reinvent**: Build on proven frameworks
+4. **Pythonic**: Feels natural to Python developers
+5. **Functional**: Prefer functions over classes
+6. **SSOT**: Single source of truth (the functions)
+7. **Open/closed**: Easy to extend, works out of the box
+
+## Conclusion
+
+`py2mcp` is essentially "qh for MCP" - the same clean, simple pattern applied to a different protocol. If you liked how qh worked, you'll feel right at home with py2mcp.
+
+The key insight: **Functions are the universal interface.** Whether exposing them via HTTP or MCP, the pattern is the same:
+
+```
+functions → wrapper → server → run
+```
+
+Simple, clean, Pythonic. ✨