mcp-as-code 0.1.1__tar.gz → 0.1.4__tar.gz

{mcp_as_code-0.1.1 → mcp_as_code-0.1.4}/.gitignore

@@ -49,3 +49,4 @@ gateway.json
 examples/**/.maco/
 examples/**/scratch/
 examples/**/maco-serve-mcp/
+examples/**/.playwright-mcp/

mcp_as_code-0.1.4/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: mcp-as-code
+Version: 0.1.4
+Summary: Execute MCP tools through generated Python code interfaces
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: matchlock==0.2.15
+Requires-Dist: mcp>=1.24.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# maco
+
+**Connect every MCP server you need, keeping your agent's context lean.**
+
+As the number of MCP servers you connect grows, tool schemas and intermediate tool call results clutter your agent's context. `maco` (mcp-as-code) collapses them all into a single endpoint with a programmatic interface.
+
+Instead of loading hundreds if not thousands of tool schemas upfront, `maco` reconstructs every MCP tool as Pydantic models and Python functions in a virtual filesystem and hands your agent just two of its favourite tools: `bash` to navigate, and `code_execute` to run. The agent discovers and composes tools as code, the thing frontier models do best.
+
+## How it works
+
+**Small context footprint:** the agent starts with two tools (`bash` and `code_execute`), not every MCP tool schema upfront.
+
+**Progressive discovery:** frontier models excel at navigating filesystems. By representing the tool interface as code on a filesystem, the agent can leverage `rg`, `fd` and all the POSIX tools to discover and execute relevant MCP tools.
+
+```bash
+tools
+├── playwright
+│   ├── browserClick.py
+│   ├── browserClose.py
+│   ├── ... many other tools
+│   └── __init__.py
+└── github
+    ├── addIssueComment.py
+    └── __init__.py
+```
+
+**Programmatic leverage:** the agent is given a real programming language, Python, allowing it to orchestrate complex control flows with exceptional context-efficiency using loops, conditions, and state management.
+
+```python
+from collections import Counter
+from tools.github import listCommits
+
+owner, repo, page, counts = "openclaw", "openclaw", 1, Counter()
+
+while True:
+    commits = listCommits(owner=owner, repo=repo, perPage=100, page=page)
+    for commit in commits:
+        login = (commit.get("author") or {}).get("login")
+        if login and "bot" not in login.lower():
+            counts[login] += 1
+    if len(commits) < 100 or page >= 20:
+        break
+    page += 1
+
+total = sum(counts.values())
+for login, count in counts.most_common():
+    if count / total < 0.01:
+        break
+    print(f"@{login}: {count} commits ({count / total:.1%})")
+```
+
+The example above illustrates the MCP code that will be executed to find the top contributors to an open-source repository.
+
+## Installation
+
+Install the Python package `mcp-as-code`; it provides the `maco` executable:
+
+```bash
+uv tool install mcp-as-code
+```
+
+Then verify the CLI:
+
+```bash
+maco version
+```
+
+## Quick start
+
+Create a `mcp.json`:
+
+```json
+{
+    "mcpServers": {
+        "playwright": {
+            "command": "npx",
+            "args": ["-y", "@playwright/mcp@latest"]
+        },
+        "github": {
+            "url": "https://api.githubcopilot.com/mcp/",
+            "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
+        }
+    }
+}
+```
+
+This config needs `npx` (for Playwright MCP), a GitHub token in `GITHUB_TOKEN`, and Docker if you use the `docker` provider.
+
+Start the `maco` MCP server:
+
+```bash
+maco serve-mcp --config mcp.json --provider docker
+```
+
+Use `--provider local` for a faster, non-isolated local feedback loop.
+
+By default this serves Streamable HTTP MCP at `http://127.0.0.1:8789/mcp`.
+
+Configure an MCP client to connect to that endpoint:
+
+<details>
+<summary>Codex</summary>
+
+```bash
+codex mcp add maco --url http://127.0.0.1:8789/mcp
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add --transport http maco http://127.0.0.1:8789/mcp
+```
+
+</details>
+
+See [`examples/serve-mcp`](examples/serve-mcp) for a complete example that wraps multiple upstream MCP servers behind one `maco` endpoint.
+
+## MCP config
+
+See [`docs/mcp-config.md`](docs/mcp-config.md) for the full config reference, including environment expansion, headers, OAuth hints, token caching, and tool filtering.
+
+## Sandbox providers
+
+Choose the execution provider with `--provider`:
+
+- `local`: fastest feedback loop; runs commands as local subprocesses.
+- `docker`: runs commands in a long-lived Docker container.
+- `matchlock`: runs commands in a long-lived Matchlock micro-VM.
+
+## License
+
+Apache License 2.0. See [`LICENSE`](LICENSE).

mcp_as_code-0.1.4/README.md

@@ -0,0 +1,135 @@
+# maco
+
+**Connect every MCP server you need, keeping your agent's context lean.**
+
+As the number of MCP servers you connect grows, tool schemas and intermediate tool call results clutter your agent's context. `maco` (mcp-as-code) collapses them all into a single endpoint with a programmatic interface.
+
+Instead of loading hundreds if not thousands of tool schemas upfront, `maco` reconstructs every MCP tool as Pydantic models and Python functions in a virtual filesystem and hands your agent just two of its favourite tools: `bash` to navigate, and `code_execute` to run. The agent discovers and composes tools as code, the thing frontier models do best.
+
+## How it works
+
+**Small context footprint:** the agent starts with two tools (`bash` and `code_execute`), not every MCP tool schema upfront.
+
+**Progressive discovery:** frontier models excel at navigating filesystems. By representing the tool interface as code on a filesystem, the agent can leverage `rg`, `fd` and all the POSIX tools to discover and execute relevant MCP tools.
+
+```bash
+tools
+├── playwright
+│   ├── browserClick.py
+│   ├── browserClose.py
+│   ├── ... many other tools
+│   └── __init__.py
+└── github
+    ├── addIssueComment.py
+    └── __init__.py
+```
+
+**Programmatic leverage:** the agent is given a real programming language, Python, allowing it to orchestrate complex control flows with exceptional context-efficiency using loops, conditions, and state management.
+
+```python
+from collections import Counter
+from tools.github import listCommits
+
+owner, repo, page, counts = "openclaw", "openclaw", 1, Counter()
+
+while True:
+    commits = listCommits(owner=owner, repo=repo, perPage=100, page=page)
+    for commit in commits:
+        login = (commit.get("author") or {}).get("login")
+        if login and "bot" not in login.lower():
+            counts[login] += 1
+    if len(commits) < 100 or page >= 20:
+        break
+    page += 1
+
+total = sum(counts.values())
+for login, count in counts.most_common():
+    if count / total < 0.01:
+        break
+    print(f"@{login}: {count} commits ({count / total:.1%})")
+```
+
+The example above illustrates the MCP code that will be executed to find the top contributors to an open-source repository.
+
+## Installation
+
+Install the Python package `mcp-as-code`; it provides the `maco` executable:
+
+```bash
+uv tool install mcp-as-code
+```
+
+Then verify the CLI:
+
+```bash
+maco version
+```
+
+## Quick start
+
+Create a `mcp.json`:
+
+```json
+{
+    "mcpServers": {
+        "playwright": {
+            "command": "npx",
+            "args": ["-y", "@playwright/mcp@latest"]
+        },
+        "github": {
+            "url": "https://api.githubcopilot.com/mcp/",
+            "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
+        }
+    }
+}
+```
+
+This config needs `npx` (for Playwright MCP), a GitHub token in `GITHUB_TOKEN`, and Docker if you use the `docker` provider.
+
+Start the `maco` MCP server:
+
+```bash
+maco serve-mcp --config mcp.json --provider docker
+```
+
+Use `--provider local` for a faster, non-isolated local feedback loop.
+
+By default this serves Streamable HTTP MCP at `http://127.0.0.1:8789/mcp`.
+
+Configure an MCP client to connect to that endpoint:
+
+<details>
+<summary>Codex</summary>
+
+```bash
+codex mcp add maco --url http://127.0.0.1:8789/mcp
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add --transport http maco http://127.0.0.1:8789/mcp
+```
+
+</details>
+
+See [`examples/serve-mcp`](examples/serve-mcp) for a complete example that wraps multiple upstream MCP servers behind one `maco` endpoint.
+
+## MCP config
+
+See [`docs/mcp-config.md`](docs/mcp-config.md) for the full config reference, including environment expansion, headers, OAuth hints, token caching, and tool filtering.
+
+## Sandbox providers
+
+Choose the execution provider with `--provider`:
+
+- `local`: fastest feedback loop; runs commands as local subprocesses.
+- `docker`: runs commands in a long-lived Docker container.
+- `matchlock`: runs commands in a long-lived Matchlock micro-VM.
+
+## License
+
+Apache License 2.0. See [`LICENSE`](LICENSE).

mcp_as_code-0.1.4/VERSION.txt

@@ -0,0 +1 @@
+0.1.4

mcp_as_code-0.1.4/docs/mcp-config.md

@@ -0,0 +1,270 @@
+# MCP configuration
+
+`maco` reads Claude-style MCP configuration files with a top-level `mcpServers` object. The same config is used by `maco gen`, `maco serve`, and `maco serve-mcp`.
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "..."
+    }
+  }
+}
+```
+
+## Supported transports
+
+| Transport | When to use it | Required fields |
+| --- | --- | --- |
+| `stdio` | Local subprocess MCP servers | `command` |
+| `http` / `streamable_http` | Remote Streamable HTTP MCP servers | `url` or `base_url` |
+| `sse` | Deprecated SSE MCP servers | `url` or `base_url` |
+
+If `type`, `server_type`, or `transport` is omitted, maco infers `http` when `url`/`base_url` is present and `stdio` otherwise.
+
+## Common fields
+
+| Field | Type | Applies to | Description |
+| --- | --- | --- | --- |
+| `type`, `server_type`, `transport` | string | all | Transport name. `streamable-http` and `streamablehttp` are normalized to `streamable_http`. |
+| `command` | string | stdio | Executable used to start the MCP server. |
+| `args` | string array | stdio | Arguments passed to `command`. |
+| `env` | object | stdio | Environment variables passed to the subprocess. Values expand `$VAR`, `${VAR}`, and `~`. |
+| `cwd` | string | stdio | Working directory for the subprocess. |
+| `url`, `base_url` | string | HTTP/SSE | MCP endpoint URL. Values expand `$VAR`, `${VAR}`, and `~`. |
+| `headers` | object | HTTP/SSE | Static HTTP headers. Values expand environment variables. |
+| `oauth` | object | HTTP/SSE | Optional OAuth hints and interaction settings. See [OAuth](#oauth). |
+| `tools`, `tool_white_list`, `tool_whitelist` | string array | all | Optional allow-list of upstream tool names to expose. |
+
+## Stdio servers
+
+Use stdio for MCP servers that run as local subprocesses.
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    }
+  }
+}
+```
+
+### Environment variables
+
+Prefer listing required environment variables under `env`. maco expands `$VAR` and `${VAR}` using the environment of the maco process, then passes the resolved values to the upstream MCP server.
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Arguments and string fields are expanded too, so this is also valid:
+
+```json
+{
+  "mcpServers": {
+    "custom": {
+      "command": "uv",
+      "args": ["run", "server.py", "--token", "$TOKEN"],
+      "env": {"TOKEN": "$TOKEN"}
+    }
+  }
+}
+```
+
+## Streamable HTTP servers
+
+Use `type: "http"` or `type: "streamable_http"` for remote Streamable HTTP MCP servers.
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "type": "http",
+      "url": "https://example.com/mcp"
+    }
+  }
+}
+```
+
+### Static headers
+
+Use `headers` for API-key or static bearer-token servers. Static `Authorization` headers take precedence over OAuth and disable OAuth for that server.
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "type": "http",
+      "url": "https://example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## SSE servers
+
+SSE is supported for compatibility with older MCP servers. Set `type: "sse"` explicitly.
+
+```json
+{
+  "mcpServers": {
+    "legacy": {
+      "type": "sse",
+      "url": "https://example.com/sse"
+    }
+  }
+}
+```
+
+## OAuth
+
+For remote HTTP/SSE servers without a static `Authorization` header, maco can automatically perform OAuth when the upstream server returns an HTTP `401` with a Bearer challenge. The flow is:
+
+1. maco sends the MCP request without a bearer token.
+2. The upstream server responds with `WWW-Authenticate: Bearer ...`.
+3. maco discovers protected-resource and authorization-server metadata.
+4. maco uses configured client hints or dynamic client registration.
+5. maco opens or prints an authorization URL.
+6. maco receives the loopback callback, exchanges the code with PKCE, caches the token, and retries the MCP request.
+
+You can omit `oauth` entirely when the provider supports standard discovery and dynamic client registration.
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "type": "http",
+      "url": "https://example.com/mcp"
+    }
+  }
+}
+```
+
+Add `oauth` when the provider needs hints such as a pre-registered client, scopes, a fixed callback URL, or non-standard metadata discovery.
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "type": "http",
+      "url": "https://example.com/mcp",
+      "oauth": {
+        "client_id": "${MCP_CLIENT_ID}",
+        "client_secret": "${MCP_CLIENT_SECRET}",
+        "scopes": ["mcp.read", "mcp.write"],
+        "redirect_uri": "http://127.0.0.1:1456/mcp/oauth/callback",
+        "auth_server_metadata_url": "https://auth.example.com/.well-known/oauth-authorization-server",
+        "interactive": "auto",
+        "open_browser": true,
+        "callback_timeout": "2m"
+      }
+    }
+  }
+}
+```
+
+### OAuth fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `client_id` | string | Pre-registered OAuth client ID. Omit when dynamic client registration is supported. |
+| `client_secret` | string | Optional client secret. When present, token requests use `client_secret_post`. |
+| `scopes` | string array | Requested OAuth scopes. If omitted, maco uses scopes from the Bearer challenge or protected-resource metadata. |
+| `redirect_uri` | string | Loopback callback URI. Defaults to an ephemeral `http://127.0.0.1:<port>/mcp/oauth/callback`. `:0` is allowed and is replaced with the actual bound port. |
+| `auth_server_metadata_url` | string | Optional direct authorization-server metadata URL for providers with non-standard discovery. |
+| `interactive` | string | `auto`, `always`, or `never`. `auto` allows browser authorization only in an interactive terminal. |
+| `open_browser` | boolean | Whether to attempt opening the default browser. The URL is always printed as a fallback. |
+| `callback_timeout` | number or string | Time to wait for the callback. Supports seconds as a number or strings like `30s`, `2m`, `1h`. |
+
+### OAuth cache and environment overrides
+
+OAuth tokens and client registration metadata are cached under:
+
+```text
+~/.maco/mcp/oauth/
+```
+
+Credential files are written with `0600` permissions.
+
+Environment variables can override interaction behavior:
+
+| Variable | Description |
+| --- | --- |
+| `MACO_MCP_OAUTH_INTERACTIVE` | Overrides `oauth.interactive`. Use `never` in CI/headless runs to fail fast. |
+| `MACO_MCP_OAUTH_OPEN_BROWSER` | Overrides `oauth.open_browser`. Accepts values like `true`, `false`, `1`, `0`. |
+| `MACO_MCP_OAUTH_CALLBACK_TIMEOUT` | Overrides `oauth.callback_timeout`. Accepts seconds or duration strings like `2m`. |
+
+## Tool filtering
+
+Use `tools`, `tool_white_list`, or `tool_whitelist` to expose only selected upstream tools through generated wrappers and the maco gateway.
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "type": "http",
+      "url": "https://example.com/mcp",
+      "tools": ["search", "fetch"]
+    }
+  }
+}
+```
+
+Filtering uses the upstream MCP tool names, not generated Python function names.
+
+## Complete mixed example
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "remote": {
+      "type": "http",
+      "url": "https://example.com/mcp",
+      "oauth": {
+        "scopes": ["mcp.read"]
+      },
+      "tools": ["search", "fetch"]
+    }
+  }
+}
+```

mcp_as_code-0.1.4/examples/serve-mcp/README.md

@@ -0,0 +1,41 @@
+# `maco serve-mcp` example
+
+This example shows how to expose several upstream MCP servers through one compact `maco serve-mcp` endpoint. The upstream servers here are:
+
+- [Playwright MCP](https://playwright.dev/mcp/introduction), launched with `npx -y @playwright/mcp@latest`
+- [GitHub MCP server](https://github.com/github/github-mcp-server), using GitHub's hosted Streamable HTTP endpoint at `https://api.githubcopilot.com/mcp/`
+
+## Prerequisites
+
+- `uv`
+- `node`/`npx`, for Playwright MCP
+- A GitHub personal access token in `GITHUB_TOKEN`, used by the hosted GitHub MCP server
+- Docker, only if you use the Docker sandbox provider
+- Optional: Matchlock, for the Matchlock sandbox provider
+
+If you are already authenticated with the GitHub CLI, export a token directly:
+
+```bash
+export GITHUB_TOKEN=$(gh auth token)
+```
+
+## 1. Start `maco serve-mcp`
+
+The short path is to run from this example directory so the defaults line up with the local files:
+
+```bash
+cd examples/serve-mcp
+uv run maco serve-mcp --provider local
+```
+
+This uses `mcp.json`, writes `.maco/gateway.json`, uses `maco-serve-mcp/` as scratch, starts the gateway, and serves HTTP MCP at `http://127.0.0.1:8789/mcp`. Add `--clean` only when you want to recreate the local generated SDK from scratch.
+
+## 2. Connect an agent to the MCP gateway
+
+Configure your MCP client with `mcp-client.json` to connect to `maco serve-mcp`. For example, in your MCP client's settings, set the MCP server URL to `http://127.0.0.1:8789/mcp`.
+
+If you are using codex you may connect to it via:
+
+```bash
+codex mcp add maco --url http://127.0.0.1:8789/mcp
+```

{mcp_as_code-0.1.1 → mcp_as_code-0.1.4}/pyproject.toml

@@ -36,6 +36,7 @@ packages = ["src/maco"]
 [tool.hatch.build.targets.sdist]
 include = [
     "src/maco",
+    "docs",
     "README.md",
     "LICENSE",
     "VERSION.txt",

mcp_as_code-0.1.4/src/maco/_build_info.py

@@ -0,0 +1,4 @@
+"""Build metadata embedded during release builds."""
+
+COMMIT_SHA = "b592f828ae0d4766fbeff34d47d0b10e6f4158e1"
+RELEASE_DATE = "2026-06-16"

{mcp_as_code-0.1.1 → mcp_as_code-0.1.4}/src/maco/cli.py

@@ -133,7 +133,10 @@ def _add_serve_mcp_options(command: argparse.ArgumentParser) -> None:
     )
     command.add_argument(
         "--matchlock-gateway-ip",
-        help="IP for --add-host <gateway-host>:<ip> inside matchlock (default: 192.168.100.1 for managed gateways)",
+        help=(
+            "IP for --add-host <gateway-host>:<ip> inside matchlock "
+            "(managed default: 192.168.64.1 on macOS, 192.168.100.1 elsewhere)"
+        ),
     )
     command.add_argument(
         "--matchlock-allow-host",