fix readme, add docs

samuelcolvin · samuelcolvin · commit 4b9203e19e6a · 2025-09-01T10:55:44.000-07:00
diff --git a/.github/worflows/ci.yml b/.github/worflows/ci.yml
@@ -0,0 +1,113 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "**"
+  pull_request: {}
+
+env:
+  COLUMNS: 150
+  UV_PYTHON: 3.13
+  UV_FROZEN: "1"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync
+
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit|${{ env.UV_PYTHON }}|${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - run: uvx pre-commit run --color=always --all-files --verbose
+        env:
+          SKIP: no-commit-to-branch
+
+  test:
+    name: test py${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: make test
+        env:
+          COVERAGE_FILE: coverage/.coverage.py${{ matrix.python-version }}
+      - name: store coverage files
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage
+          include-hidden-files: true
+
+  coverage:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - name: get coverage files
+        uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+          path: coverage
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uvx coverage combine coverage
+      - run: uvx coverage report --fail-under 90
+
+  check:
+    if: always()
+    needs: [lint, test, coverage]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}
+
+  release:
+    needs: [check]
+    if: success() && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/mcp-run-python/${{ steps.check-package-version.outputs.VERSION }}
+    permissions:
+      id-token: write
+    outputs:
+      package-version: ${{ steps.check-python-version.outputs.VERSION }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - id: check-package-version
+        uses: samuelcolvin/check-python-version@v5
+        with:
+          version_file_path: packages/python/pyproject.toml
+
+      - run: uv build
+
+      - run: uv publish --trusted-publishing always
diff --git a/Makefile b/Makefile
@@ -57,8 +57,9 @@ typecheck-py: ## Typecheck the code
 typecheck: typecheck-ts typecheck-py ## Typecheck all code
 
 .PHONY: test
-test: ## Run tests
+test: ## Run tests and collect coverage data
 	uv run coverage run -m pytest
+	@uv run coverage report
 
 .PHONY: all
 all: format typecheck test ## run format, typecheck and test
diff --git a/README.md b/README.md
@@ -7,57 +7,40 @@ the rest of the operating system.
 
 **See <https://ai.pydantic.dev/mcp/run-python/> for complete documentation.**
 
-The server can be run with `deno` installed using:
+To use this server, you must have both Python and [Deno](https://deno.com/) installed
+
+The server can be run with `deno` installed using `uvx`:
 
 ```bash
-deno run \
-  -N -R=node_modules -W=node_modules --node-modules-dir=auto \
-  jsr:@pydantic/mcp-run-python [stdio|streamable_http|sse|warmup]
+uvx mcp-run-python [stdio|streamable-http|warmup]
 ```
 
 where:
 
-- `-N -R=node_modules -W=node_modules` (alias of `--allow-net --allow-read=node_modules --allow-write=node_modules`)
-  allows network access and read+write access to `./node_modules`. These are required so pyodide can download and cache
-  the Python standard library and packages
-- `--node-modules-dir=auto` tells deno to use a local `node_modules` directory
 - `stdio` runs the server with the
   [Stdio MCP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) — suitable for
   running the process as a subprocess locally
-- `streamable_http` runs the server with the
+- `streamable-http` runs the server with the
   [Streamable HTTP MCP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) -
   suitable for running the server as an HTTP server to connect locally or remotely. This supports stateful requests, but
   does not require the client to hold a stateful connection like SSE
-- `sse` runs the server with the
-  [SSE MCP transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) —
-  suitable for running the server as an HTTP server to connect locally or remotely. Note that the SSE transport has been
-  [deprecated in newer MCP protocol versions](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#backwards-compatibility)
-  and is there to maintain backwards compatibility.
 - `warmup` will run a minimal Python script to download and cache the Python standard library. This is also useful to
   check the server is running correctly.
 
-Here's an example of using `@pydantic/mcp-run-python` with Pydantic AI:
+Here's an example of using `mcp-run-python` with Pydantic AI:
 
 ```python
 from pydantic_ai import Agent
 from pydantic_ai.mcp import MCPServerStdio
+from mcp_run_python import deno_args
 
 import logfire
 
 logfire.configure()
 logfire.instrument_mcp()
 logfire.instrument_pydantic_ai()
 
-server = MCPServerStdio('deno',
-    args=[
-        'run',
-        '-N',
-        '-R=node_modules',
-        '-W=node_modules',
-        '--node-modules-dir=auto',
-        'jsr:@pydantic/mcp-run-python',
-        'stdio',
-    ])
+server = MCPServerStdio('deno', args=deno_args('stdio'))
 agent = Agent('claude-3-5-haiku-latest', toolsets=[server])
 
 
diff --git a/mcp_run_python/py.typed b/mcp_run_python/py.typed
diff --git a/pydantic_ai_example.py b/pydantic_ai_example.py
@@ -0,0 +1,36 @@
+# /// script
+# requires-python = ">=3.13"
+# dependencies = [
+#     "logfire",
+#     "mcp-run-python",
+#     "pydantic-ai-slim[mcp,anthropic]",
+# ]
+#
+# [tool.uv.sources]
+# mcp-run-python = { path = "." }
+# ///
+import logfire
+from pydantic_ai import Agent
+from pydantic_ai.mcp import MCPServerStdio
+
+from mcp_run_python import deno_args
+
+logfire.configure()
+logfire.instrument_mcp()
+logfire.instrument_pydantic_ai()
+
+server = MCPServerStdio('deno', args=deno_args('stdio'))
+agent_with_python = Agent('claude-3-5-haiku-latest', toolsets=[server])
+
+
+async def main():
+    async with agent_with_python:
+        result = await agent_with_python.run('How many days between 2000-01-01 and 2025-03-18?')
+    print(result.output)
+    # > There are 9,208 days between January 1, 2000, and March 18, 2025.w
+
+
+if __name__ == '__main__':
+    import asyncio
+
+    asyncio.run(main())
diff --git a/pyproject.toml b/pyproject.toml
@@ -38,7 +38,8 @@ Changelog = "https://github.com/pydantic/mcp-run-python/releases"
 [tool.uv.build-backend]
 module-name = "mcp_run_python"
 module-root = ""
-
+source-exclude = ["node_modules"]
+wheel-exclude = ["node_modules"]
 
 [dependency-groups]
 dev = [
@@ -51,6 +52,7 @@ dev = [
     "pytest>=8.3.3",
     "pytest-pretty>=1.2.0",
     "ruff>=0.12.11",
+    "coverage>=7.10.6",
 ]
 
 [project.scripts]
diff --git a/uv.lock b/uv.lock
