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

mcp_as_code-0.1.5/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: mcp-as-code
+Version: 0.1.5
+Summary: Execute MCP tools through generated Python code interfaces
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.28
+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 up --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.5/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 up --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.2 → mcp_as_code-0.1.5}/docs/mcp-config.md

@@ -1,6 +1,6 @@
 # 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`.
+`maco` reads Claude-style MCP configuration files with a top-level `mcpServers` object. The same config is used by `maco gen` and `maco up`.
 
 ```json
 {

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

@@ -0,0 +1,41 @@
+# `maco up` example
+
+This example shows how to expose several upstream MCP servers through one compact `maco up` 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 up`
+
+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 up --provider local
+```
+
+This uses `mcp.json`, writes `.maco/gateway.json`, uses `.maco/scratch` as the default scratch directory, 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 up`. 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.2 → mcp_as_code-0.1.5}/images/sandbox/README.md

@@ -1,20 +1,20 @@
 # maco sandbox image
 
-This directory contains the Docker image used by the Docker and Matchlock `maco serve-mcp` sandbox providers.
+This directory contains the Docker image used by the Docker and Matchlock `maco up` sandbox providers.
 
 The image extends the pinned Alpine uv/Python image with the `maco` CLI, `ripgrep` (`rg`), and `fd`. Remote sandbox providers use the CLI to bootstrap `/workspace/macosdk/tools` from the live gateway catalog at sandbox startup.
 
 ## Build
 
 ```bash
-VERSION="$(cat VERSION.txt)"
+VERSION="$(scripts/package-version)"
 docker build -f images/sandbox/Dockerfile -t "ghcr.io/jingkaihe/maco:${VERSION}-alpine" .
 ```
 
 ## Import into Matchlock
 
 ```bash
-VERSION="$(cat VERSION.txt)"
+VERSION="$(scripts/package-version)"
 docker save "ghcr.io/jingkaihe/maco:${VERSION}-alpine" \
   | matchlock image import "ghcr.io/jingkaihe/maco:${VERSION}-alpine"
 ```

{mcp_as_code-0.1.2 → mcp_as_code-0.1.5}/pyproject.toml

@@ -6,6 +6,8 @@ readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.11"
 dependencies = [
+    "click>=8.1",
+    "httpx>=0.28",
     "jinja2>=3.1",
     "matchlock==0.2.15",
     "mcp>=1.24.0",
@@ -27,8 +29,7 @@ dev = [
 ]
 
 [tool.hatch.version]
-path = "VERSION.txt"
-pattern = "(?P<version>.+)"
+path = "src/maco/__init__.py"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/maco"]
@@ -39,6 +40,5 @@ include = [
     "docs",
     "README.md",
     "LICENSE",
-    "VERSION.txt",
     "pyproject.toml",
 ]

{mcp_as_code-0.1.2 → mcp_as_code-0.1.5}/src/maco/__init__.py

@@ -1,3 +1,3 @@
 """maco Python interface generator and MCP code-execution server."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.5"