intuned-agent-mcp 0.1.0__tar.gz

intuned_agent_mcp-0.1.0/.env

@@ -0,0 +1,12 @@
+# Generated by `yarn local:setup:*` from .env.tpl. Do not edit by hand.
+# CLAUDE_SDK_WORKING_DIRECTORY is injected by the Claude Agent SDK at spawn.
+
+# Prevent litellm from fetching remote model cost data at import time
+LITELLM_LOCAL_MODEL_COST_MAP=True
+
+ANTHROPIC_API_KEY="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"
+GEMINI_API_KEY="AIzaSyChS2tjH5--n2LtrMiB1EST7CwA3XA0R2A"
+
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY="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"
+LANGSMITH_PROJECT=intuned-agent-mcp

intuned_agent_mcp-0.1.0/.env.tpl

@@ -0,0 +1,12 @@
+# Generated by `yarn local:setup:*` from .env.tpl. Do not edit by hand.
+# CLAUDE_SDK_WORKING_DIRECTORY is injected by the Claude Agent SDK at spawn.
+
+# Prevent litellm from fetching remote model cost data at import time
+LITELLM_LOCAL_MODEL_COST_MAP=True
+
+ANTHROPIC_API_KEY={{ANTHROPIC_API_KEY}}
+GEMINI_API_KEY={{GEMINI_API_KEY}}
+
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY={{LANGSMITH_API_KEY}}
+LANGSMITH_PROJECT=intuned-agent-mcp

intuned_agent_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.intuned/
+.intuned-agent/
+.dev-workspace/
+mcp-server.log
+src/intuned_agent_mcp/tool_schemas.json

intuned_agent_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

intuned_agent_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: intuned-agent-mcp
+Version: 0.1.0
+Summary: MCP server exposing browser automation tools via intuned-runtime
+Requires-Python: <4.0,>=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: intuned-browser
+Requires-Dist: intuned-runtime>=1.3.24
+Requires-Dist: langchain-anthropic>=0.2.0
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: langsmith>=0.1.0
+Requires-Dist: lxml>=5.0
+Requires-Dist: mcp<2.0,>=1.0
+Requires-Dist: playwright<2,>=1.58.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Intuned Agent MCP Server
+
+An MCP server exposing browser automation tools: navigation, DOM inspection, element finding, and computer-use actions (click, type, scroll, screenshot). It speaks MCP over stdio.
+
+## Run with uvx
+
+```bash
+uvx intuned-agent-mcp
+```
+
+To use it from an MCP client, point the client at the `uvx` command:
+
+```json
+{
+  "mcpServers": {
+    "intuned-agent-mcp": {
+      "command": "uvx",
+      "args": ["intuned-agent-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool                   | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `navigate`             | Navigate to a URL, or go back/forward in browser history        |
+| `find`                 | Find elements using natural language descriptions or exact text |
+| `query_by_selector`    | Search for DOM elements using CSS selector or XPath             |
+| `find_array_container` | Find the DOM container holding a collection of related items    |
+| `inspect_element`      | Inspect a specific element and return a collapsed DOM preview   |
+| `scroll_into_view`     | Scroll an element into the viewport                             |
+| `computer`             | Mouse clicks, keyboard input, scrolling, and screenshots        |
+| `select_option`        | Select an option from a dropdown or select element              |
+
+## Configuration
+
+Logging is off by default. To enable it, set environment variables:
+
+| Variable       | Description                                            |
+| -------------- | ------------------------------------------------------ |
+| `MCP_LOG_FILE` | Path to write logs to. Logs are disabled when not set. |
+| `MCP_DEBUG`    | Set to `1` to log at `DEBUG` level (default `INFO`).   |
+
+## Requirements
+
+- Python 3.12+
+- A Chromium-based browser reachable over the Chrome DevTools Protocol. Browser-driving tools connect to an existing browser over CDP.

intuned_agent_mcp-0.1.0/README.md

@@ -0,0 +1,49 @@
+# Intuned Agent MCP Server
+
+An MCP server exposing browser automation tools: navigation, DOM inspection, element finding, and computer-use actions (click, type, scroll, screenshot). It speaks MCP over stdio.
+
+## Run with uvx
+
+```bash
+uvx intuned-agent-mcp
+```
+
+To use it from an MCP client, point the client at the `uvx` command:
+
+```json
+{
+  "mcpServers": {
+    "intuned-agent-mcp": {
+      "command": "uvx",
+      "args": ["intuned-agent-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool                   | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `navigate`             | Navigate to a URL, or go back/forward in browser history        |
+| `find`                 | Find elements using natural language descriptions or exact text |
+| `query_by_selector`    | Search for DOM elements using CSS selector or XPath             |
+| `find_array_container` | Find the DOM container holding a collection of related items    |
+| `inspect_element`      | Inspect a specific element and return a collapsed DOM preview   |
+| `scroll_into_view`     | Scroll an element into the viewport                             |
+| `computer`             | Mouse clicks, keyboard input, scrolling, and screenshots        |
+| `select_option`        | Select an option from a dropdown or select element              |
+
+## Configuration
+
+Logging is off by default. To enable it, set environment variables:
+
+| Variable       | Description                                            |
+| -------------- | ------------------------------------------------------ |
+| `MCP_LOG_FILE` | Path to write logs to. Logs are disabled when not set. |
+| `MCP_DEBUG`    | Set to `1` to log at `DEBUG` level (default `INFO`).   |
+
+## Requirements
+
+- Python 3.12+
+- A Chromium-based browser reachable over the Chrome DevTools Protocol. Browser-driving tools connect to an existing browser over CDP.

intuned_agent_mcp-0.1.0/RELEASING.md

@@ -0,0 +1,144 @@
+# Releasing `intuned-agent-mcp`
+
+Internal guide for publishing the browser-automation MCP server to PyPI so it can
+be run with `uvx intuned-agent-mcp`. The `intuned` Claude Code plugin launches the
+server this way (see the plugin's `.mcp.json`).
+
+## Quick release (script)
+
+`scripts/release.py` bumps the version, builds, and publishes in one step:
+
+```bash
+# dev -> TestPyPI
+uv run scripts/release.py dev 0.1.1.dev0
+
+# prod -> PyPI
+uv run scripts/release.py prod 0.1.1
+```
+
+Publishing goes through `twine`, which reads credentials from `~/.pypirc`
+(`[pypi]` for prod, `[testpypi]` for dev; username `__token__`, password your API
+token). The script prints the matching smoke-test command when it finishes. The
+rest of this doc explains each step and the one-time account setup.
+
+## What makes it runnable via uvx
+
+Three things in `pyproject.toml` must stay intact:
+
+- `name = "intuned-agent-mcp"` and a bumped `version`.
+- `readme = "README.md"` so PyPI renders a page.
+- A console-script entry point:
+  ```toml
+  [project.scripts]
+  intuned-agent-mcp = "intuned_agent_mcp.__main__:main"
+  ```
+  This is what `uvx intuned-agent-mcp` resolves to. Without it there is no command
+  to run.
+
+Dependencies (`intuned-runtime`, `intuned-browser`, `playwright`, `mcp`,
+`langchain*`, etc.) all resolve from public PyPI.
+
+## Prerequisites
+
+- `uv` on `PATH` (`uv --version`).
+- A PyPI account + API token, and a TestPyPI account + API token (separate sites,
+  separate accounts). 2FA must be enabled before you can create tokens.
+  - For a brand-new project, the first upload needs an **account-scoped** token
+    (a project-scoped token cannot exist until the project does). Rotate to a
+    project-scoped token after the first publish.
+- Tokens are passed via `--token pypi-...`. Do not commit them.
+
+## 1. Bump the version
+
+Edit `version` in `pyproject.toml` (e.g. `0.1.0` -> `0.1.1`). PyPI refuses to
+re-upload an existing version, so every publish needs a new number.
+
+## 2. Build
+
+```bash
+cd apps/intuned-agent-mcp
+rm -rf dist && uv build
+```
+
+This produces `dist/intuned_agent_mcp-<version>.tar.gz` (sdist) and
+`...-py3-none-any.whl` (wheel). Quick sanity checks:
+
+```bash
+unzip -p dist/*.whl '*/entry_points.txt'   # should show the intuned-agent-mcp console_script
+unzip -p dist/*.whl '*/METADATA' | grep -i description-content-type   # text/markdown
+```
+
+## 3. Publish to TestPyPI first
+
+The `testpypi` index is preconfigured in `pyproject.toml` with both an install
+`url` and a `publish-url`:
+
+```toml
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+```
+
+Publish:
+
+```bash
+uv publish --index testpypi --token pypi-<TESTPYPI_TOKEN>
+```
+
+Smoke-test the published artifact. TestPyPI does not mirror the dependencies, so
+point uv at TestPyPI for the package and let it fall through to real PyPI for the
+rest:
+
+```bash
+uvx --index https://test.pypi.org/simple/ --index-strategy unsafe-best-match intuned-agent-mcp
+```
+
+It should start and block on stdin (it is an MCP stdio server). No traceback means
+the entry point and packaging are good. Ctrl+C to exit.
+
+## 4. Publish to real PyPI
+
+```bash
+uv publish --token pypi-<PYPI_TOKEN>
+uvx intuned-agent-mcp   # final smoke test, no index flags needed
+```
+
+## 5. Post-publish: simplify the plugin config
+
+While testing, the plugin's `.mcp.json` resolves the server from TestPyPI:
+
+```json
+"browser": {
+  "command": "uvx",
+  "args": [
+    "--index", "https://test.pypi.org/simple/",
+    "--index-strategy", "unsafe-best-match",
+    "intuned-agent-mcp"
+  ]
+}
+```
+
+Once the version is on real PyPI, drop the index flags:
+
+```json
+"browser": { "command": "uvx", "args": ["intuned-agent-mcp"] }
+```
+
+The plugin lives in the `Intuned/skills` repo under `intuned-plugin/.mcp.json`.
+Consider pinning the version there (`intuned-agent-mcp==<version>`) so a later
+publish does not silently change plugin behavior.
+
+## Notes
+
+- **Playwright browsers are not bundled.** `uvx` installs the `playwright` wheel
+  but not the browser binaries. The plugin drives an existing browser over CDP, so
+  this is fine in that flow; a standalone user would need `playwright install`.
+- **Logging is off by default.** Set `MCP_LOG_FILE=/path` (and optionally
+  `MCP_DEBUG=1`) to write logs to a file. The server never logs to stderr.
+- **First-run latency.** `uvx` resolves and caches the dependency tree on first
+  launch, so the first start is slow; later starts are cached.
+- `[tool.uv] exclude-newer` in `pyproject.toml` pins the resolver to packages
+  published before a cutoff for reproducibility; bump or remove it if a needed
+  dependency release is newer than the window.

intuned_agent_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "intuned-agent-mcp"
+version = "0.1.0"
+description = "MCP server exposing browser automation tools via intuned-runtime"
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "intuned-browser",
+    "intuned-runtime>=1.3.24",
+    "playwright>=1.58.0,<2",
+    "mcp>=1.0,<2.0",
+    "pydantic>=2.0",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.0",
+    # LangChain dependencies for selector tools
+    "langgraph>=0.2.0",
+    "langchain>=0.3.0",
+    "langchain-anthropic>=0.2.0",
+    "httpx>=0.27.0",
+    "langsmith>=0.1.0",
+]
+
+[project.scripts]
+intuned-agent-mcp = "intuned_agent_mcp.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.7.0",
+    "pyright>=1.1.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["src"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "e2e: marks tests as end-to-end (deselect with '-m \"not e2e\"')",
+    "headed: marks tests that require a headed browser",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+fix = false
+show-fixes = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP", "W", "N", "PTH", "C4", "ASYNC", "T20"]
+ignore = ["E501", "E722", "ASYNC109"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/test_*.py" = ["T20"]
+"**/tests/*.py" = ["T20"]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+order-by-type = false
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "basic"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/intuned_agent_mcp"]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.uv]
+exclude-newer = "7d"

intuned_agent_mcp-0.1.0/scripts/compare_experiments.py

@@ -0,0 +1,168 @@
+# ruff: noqa: T201  # CLI script — print() is intentional
+#!/usr/bin/env python3
+"""
+Compare two LangSmith experiments from the reliable-selector-builder dataset, side by side.
+
+`--a` and `--b` accept either a full experiment name or just the short preset prefix
+(matching the `short` field in MODEL_PRESETS). When a prefix is passed, the split name
+gets appended automatically, so a prefix like `flash-haikufb` combined with
+`--split hard` resolves to the newest project matching `flash-haikufb-hard`.
+
+Usage:
+  uv run python scripts/compare_experiments.py --split smoke
+  uv run python scripts/compare_experiments.py --a haiku --b flash-haikufb --split hard
+  uv run python scripts/compare_experiments.py --a haiku-haiku-smoke-fb374d62 --b flash-haikufb-smoke-4c716e4d
+
+Env vars (same as run_selector_experiment.py): LANGSMITH_API_KEY in .env.
+"""
+
+import argparse
+from dataclasses import dataclass
+from typing import Any
+
+from dotenv import load_dotenv
+
+DATASET_ID = "fae8988e-2753-4aef-bb53-e2f9b0120a36"
+DEFAULT_A_PREFIX = "haiku"
+DEFAULT_B_PREFIX = "flash-haikufb"
+DEFAULT_SPLIT = "smoke"
+SEPARATOR_WIDTH = 110
+
+
+@dataclass
+class RunRecord:
+    outputs: dict[str, Any] | None
+    error: str | None
+    latency: float | None
+
+
+def _extract_selectors(container: dict[str, Any] | None) -> list[tuple[str, str]]:
+    """Extract [(type, value), ...] from an object with a `selectors` key.
+
+    Used for both dataset reference outputs and experiment run outputs.
+    """
+    if not container:
+        return []
+    return [(s.get("type", ""), s.get("value", "")) for s in container.get("selectors", [])]
+
+
+def _resolve_project(client, name_or_prefix: str) -> str:
+    """Return the exact project name for a hit in LangSmith.
+
+    Exact match wins if found; otherwise the most recently started project whose
+    name contains the prefix is used.
+    """
+    candidates = list(client.list_projects(name_contains=name_or_prefix))
+    if not candidates:
+        raise SystemExit(f"No LangSmith project matches {name_or_prefix!r}")
+    for p in candidates:
+        if p.name == name_or_prefix:
+            return p.name
+    candidates.sort(key=lambda p: getattr(p, "start_time", None) or p.id, reverse=True)
+    return candidates[0].name
+
+
+def _load_runs(client, project_name: str) -> dict[str, RunRecord]:
+    """Load root runs from a project keyed by reference example id."""
+    runs = list(client.list_runs(project_name=project_name, is_root=True))
+    out: dict[str, RunRecord] = {}
+    for r in runs:
+        ref = getattr(r, "reference_example_id", None)
+        if ref is None:
+            continue
+        out[str(ref)] = RunRecord(
+            outputs=r.outputs,
+            error=r.error,
+            latency=(r.end_time - r.start_time).total_seconds() if r.end_time else None,
+        )
+    return out
+
+
+def _fmt_latency(record: RunRecord | None) -> str:
+    if record is None or record.latency is None:
+        return "—"
+    return f"{record.latency:.1f}s"
+
+
+def _print_selectors(label: str, record: RunRecord | None, max_len: int) -> None:
+    if record is None:
+        print(f"     {label}:   <missing>")
+        return
+    for j, (kind, value) in enumerate(_extract_selectors(record.outputs)):
+        print(f"     {label}    [{j}]: {kind:5s} {value[:max_len]}")
+
+
+def main() -> None:
+    load_dotenv()
+
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--a", default=DEFAULT_A_PREFIX, help="First experiment name or short prefix")
+    parser.add_argument("--b", default=DEFAULT_B_PREFIX, help="Second experiment name or short prefix")
+    parser.add_argument("--split", default=DEFAULT_SPLIT, help="Dataset split to compare")
+    parser.add_argument("--max-len", type=int, default=140, help="Truncate selector strings to this length")
+    args = parser.parse_args()
+
+    # If the user passed a bare preset short (no `-<split>-<hash>` suffix), append the split
+    # so they don't have to retype it for every run.
+    def _with_split(name: str) -> str:
+        return name if args.split in name else f"{name}-{args.split}"
+
+    from langsmith import Client
+
+    client = Client()
+    exp_a = _resolve_project(client, _with_split(args.a))
+    exp_b = _resolve_project(client, _with_split(args.b))
+    print(f"A = {exp_a}")
+    print(f"B = {exp_b}")
+
+    runs_a = _load_runs(client, exp_a)
+    runs_b = _load_runs(client, exp_b)
+
+    examples = list(client.list_examples(dataset_id=DATASET_ID, splits=[args.split]))
+    print(f"Split {args.split}: {len(examples)} examples  (A landed: {len(runs_a)}, B landed: {len(runs_b)})")
+    print("=" * SEPARATOR_WIDTH)
+
+    a_ok = b_ok = agree = both_landed = 0
+    for i, ex in enumerate(examples, 1):
+        ex_id = str(ex.id)
+        ref = _extract_selectors(ex.outputs)
+        ra, rb = runs_a.get(ex_id), runs_b.get(ex_id)
+
+        inputs = ex.inputs or {}
+        desc = (inputs.get("description") or "")[:100]
+        candidates = inputs.get("candidates", [])
+        ncands = len(candidates)
+        has_container = any(c.get("container_full_xpath") for c in candidates)
+
+        print(
+            f"\n[{i:>2}] id={ex_id[:8]}  cands={ncands}  container={has_container}  "
+            f"lat A={_fmt_latency(ra)} B={_fmt_latency(rb)}"
+        )
+        print(f"     desc: {desc}")
+        for j, (kind, value) in enumerate(ref):
+            print(f"     REF  [{j}]: {kind:5s} {value[: args.max_len]}")
+        _print_selectors("A", ra, args.max_len)
+        _print_selectors("B", rb, args.max_len)
+
+        if ra is not None and rb is not None:
+            both_landed += 1
+            a_sel = _extract_selectors(ra.outputs)
+            b_sel = _extract_selectors(rb.outputs)
+            heq = a_sel == ref
+            geq = b_sel == ref
+            ag = a_sel == b_sel
+            a_ok += int(heq)
+            b_ok += int(geq)
+            agree += int(ag)
+            print(f"     >> A==ref: {heq}  B==ref: {geq}  A==B: {ag}")
+
+    print("\n" + "=" * SEPARATOR_WIDTH)
+    print(f"Landed in both: {both_landed}/{len(examples)}")
+    print(f"A exact-match vs ref: {a_ok}/{both_landed}")
+    print(f"B exact-match vs ref: {b_ok}/{both_landed}")
+    print(f"A == B selectors:     {agree}/{both_landed}")
+    print("(exact-match is a weak metric: the dataset ref is one valid selector among many)")
+
+
+if __name__ == "__main__":
+    main()