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

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

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

{mcp_as_code-0.1.1 → mcp_as_code-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-as-code
-Version: 0.1.1
+Version: 0.1.2
 Summary: Execute MCP tools through generated Python code interfaces
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -141,32 +141,22 @@ If you are using the source checkout directly, the script wrapper is equivalent:
 
 ## MCP config
 
-`maco` expects Claude-style JSON with a top-level `mcpServers` object.
+`maco` expects Claude-style JSON with a top-level `mcpServers` object. Supported upstream transports are `stdio`, `http`/`streamable_http`, and `sse`.
 
-For environment variables, put them under `env`. `maco` expands `$VAR` and `${VAR}` using the environment of the `maco` process, then passes the resolved values to the upstream MCP server:
+Minimal stdio example:
 
 ```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}"
-      }
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
     }
   }
 }
 ```
 
-HTTP-style servers can use URL and header fields:
+Minimal Streamable HTTP example:
 
 ```json
 {
@@ -180,7 +170,7 @@ HTTP-style servers can use URL and header fields:
 }
 ```
 
-Supported transports are `stdio`, `http`/`streamable_http`, and `sse`.
+For remote HTTP/SSE servers without a static `Authorization` header, maco can perform OAuth from the upstream server's HTTP `401 Bearer` challenge. 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
 

{mcp_as_code-0.1.1 → mcp_as_code-0.1.2}/README.md

@@ -128,32 +128,22 @@ If you are using the source checkout directly, the script wrapper is equivalent:
 
 ## MCP config
 
-`maco` expects Claude-style JSON with a top-level `mcpServers` object.
+`maco` expects Claude-style JSON with a top-level `mcpServers` object. Supported upstream transports are `stdio`, `http`/`streamable_http`, and `sse`.
 
-For environment variables, put them under `env`. `maco` expands `$VAR` and `${VAR}` using the environment of the `maco` process, then passes the resolved values to the upstream MCP server:
+Minimal stdio example:
 
 ```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}"
-      }
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
     }
   }
 }
 ```
 
-HTTP-style servers can use URL and header fields:
+Minimal Streamable HTTP example:
 
 ```json
 {
@@ -167,7 +157,7 @@ HTTP-style servers can use URL and header fields:
 }
 ```
 
-Supported transports are `stdio`, `http`/`streamable_http`, and `sse`.
+For remote HTTP/SSE servers without a static `Authorization` header, maco can perform OAuth from the upstream server's HTTP `401 Bearer` challenge. 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
 

mcp_as_code-0.1.2/VERSION.txt

@@ -0,0 +1 @@
+0.1.2

mcp_as_code-0.1.2/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.1 → mcp_as_code-0.1.2}/examples/serve-mcp/README.md

@@ -36,7 +36,7 @@ MCP client ──HTTP──▶ maco serve-mcp ──sandbox──▶ generated P
 If you are already authenticated with the GitHub CLI, export a token directly:
 
 ```bash
-export GITHUB_PERSONAL_ACCESS_TOKEN=$(gh auth token)
+export GITHUB_TOKEN=$(gh auth token)
 ```
 
 ## 1. Start `maco serve-mcp`

{mcp_as_code-0.1.1 → mcp_as_code-0.1.2}/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.2/src/maco/_build_info.py

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

{mcp_as_code-0.1.1 → mcp_as_code-0.1.2}/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",

{mcp_as_code-0.1.1 → mcp_as_code-0.1.2}/src/maco/config.py

@@ -13,6 +13,20 @@ class ConfigError(ValueError):
     """Raised when an MCP configuration file is invalid."""
 
 
+@dataclass(frozen=True)
+class OAuthConfig:
+    """Optional OAuth hints for remote HTTP/SSE MCP servers."""
+
+    client_id: str | None = None
+    client_secret: str | None = None
+    scopes: list[str] = field(default_factory=list)
+    redirect_uri: str | None = None
+    auth_server_metadata_url: str | None = None
+    interactive: str | None = None
+    open_browser: bool | None = None
+    callback_timeout: float | None = None
+
+
 @dataclass(frozen=True)
 class ServerConfig:
     """Configuration for one MCP server."""
@@ -25,6 +39,7 @@ class ServerConfig:
     cwd: str | None = None
     base_url: str | None = None
     headers: dict[str, str] = field(default_factory=dict)
+    oauth: OAuthConfig | None = None
     tool_white_list: list[str] = field(default_factory=list)
 
     @property
@@ -104,6 +119,7 @@ def _parse_server(name: str, raw: dict[str, Any]) -> ServerConfig:
 
     env = _string_map(raw.get("env") or {})
     headers = _string_map(raw.get("headers") or {})
+    oauth = _parse_oauth(name, raw.get("oauth"))
     args = raw.get("args") or []
     if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
         raise ConfigError(f"server {name!r} args must be a list of strings")
@@ -137,10 +153,79 @@ def _parse_server(name: str, raw: dict[str, Any]) -> ServerConfig:
         cwd=cwd,
         base_url=base_url,
         headers=headers,
+        oauth=oauth,
         tool_white_list=white_list,
     )
 
 
+def _parse_oauth(name: str, raw: Any) -> OAuthConfig | None:
+    if raw is None or raw is False:
+        return None
+    if raw is True:
+        raw = {}
+    if not isinstance(raw, dict):
+        raise ConfigError(f"server {name!r} oauth must be an object")
+
+    scopes = raw.get("scopes") or []
+    if not isinstance(scopes, list) or not all(isinstance(scope, str) for scope in scopes):
+        raise ConfigError(f"server {name!r} oauth scopes must be a list of strings")
+
+    interactive = _optional_expanded(raw.get("interactive"))
+    if interactive is not None:
+        interactive = interactive.strip().lower()
+
+    return OAuthConfig(
+        client_id=_optional_expanded(raw.get("client_id")),
+        client_secret=_optional_expanded(raw.get("client_secret")),
+        scopes=[_expand_value(scope) for scope in scopes],
+        redirect_uri=_optional_expanded(raw.get("redirect_uri")),
+        auth_server_metadata_url=_optional_expanded(raw.get("auth_server_metadata_url")),
+        interactive=interactive,
+        open_browser=_optional_bool(name, raw.get("open_browser")),
+        callback_timeout=_optional_duration_seconds(name, raw.get("callback_timeout")),
+    )
+
+
+def _optional_bool(name: str, value: Any) -> bool | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = _expand_value(value).strip().lower()
+        if normalized in {"1", "true", "yes", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "off"}:
+            return False
+    raise ConfigError(f"server {name!r} oauth open_browser must be a boolean")
+
+
+def _optional_duration_seconds(name: str, value: Any) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, int | float):
+        seconds = float(value)
+    elif isinstance(value, str):
+        seconds = _parse_duration_seconds(_expand_value(value).strip())
+    else:
+        raise ConfigError(
+            f"server {name!r} oauth callback_timeout must be a number or duration string"
+        )
+    if seconds <= 0:
+        raise ConfigError(f"server {name!r} oauth callback_timeout must be positive")
+    return seconds
+
+
+def _parse_duration_seconds(value: str) -> float:
+    if not value:
+        raise ConfigError("oauth callback_timeout must not be empty")
+    multipliers = {"ms": 0.001, "s": 1.0, "m": 60.0, "h": 3600.0}
+    for suffix, multiplier in multipliers.items():
+        if value.endswith(suffix):
+            return float(value[: -len(suffix)]) * multiplier
+    return float(value)
+
+
 def _infer_server_type(raw: dict[str, Any]) -> str:
     if raw.get("base_url") or raw.get("url"):
         return "http"

{mcp_as_code-0.1.1 → mcp_as_code-0.1.2}/src/maco/mcp_manager.py

@@ -4,14 +4,19 @@ from __future__ import annotations
 
 import contextlib
 from dataclasses import dataclass
-from typing import Any, AsyncIterator
+from typing import Any, AsyncIterator, Protocol, cast
 
 from mcp import ClientSession
 from mcp.client.sse import sse_client
 from mcp.client.stdio import StdioServerParameters, stdio_client
-from mcp.client.streamable_http import streamable_http_client
+from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
 
 from .config import MacoConfig, ServerConfig
+from .oauth import make_oauth_auth
+
+
+class _Closeable(Protocol):
+    def close(self) -> None: ...
 
 
 @dataclass
@@ -123,15 +128,21 @@ async def _client_streams(server: ServerConfig) -> AsyncIterator[tuple[Any, Any]
         return
 
     if server.is_streamable_http:
-        if server.headers:
-            import httpx
-
-            async with httpx.AsyncClient(headers=server.headers, follow_redirects=True) as http_client:
-                async with streamable_http_client(
-                    server.base_url or "",
-                    http_client=http_client,
-                ) as (read_stream, write_stream, _get_session_id):
-                    yield read_stream, write_stream
+        auth = make_oauth_auth(server)
+        if server.headers or auth:
+            try:
+                async with create_mcp_http_client(
+                    headers=server.headers or None,
+                    auth=auth,
+                ) as http_client:
+                    async with streamable_http_client(
+                        server.base_url or "",
+                        http_client=http_client,
+                    ) as (read_stream, write_stream, _get_session_id):
+                        yield read_stream, write_stream
+            finally:
+                if hasattr(auth, "close"):
+                    cast(_Closeable, auth).close()
         else:
             async with streamable_http_client(server.base_url or "") as (
                 read_stream,
@@ -142,8 +153,17 @@ async def _client_streams(server: ServerConfig) -> AsyncIterator[tuple[Any, Any]
         return
 
     if server.is_sse:
-        async with sse_client(server.base_url or "", headers=server.headers or None) as streams:
-            yield streams
+        auth = make_oauth_auth(server)
+        try:
+            async with sse_client(
+                server.base_url or "",
+                headers=server.headers or None,
+                auth=auth,
+            ) as streams:
+                yield streams
+        finally:
+            if hasattr(auth, "close"):
+                cast(_Closeable, auth).close()
         return
 
     raise ValueError(f"unsupported MCP server transport for {server.name}: {server.server_type}")