notte-mcp 1.4.4__tar.gz

notte_mcp-1.4.4/.gitignore

@@ -0,0 +1,181 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+ignore.*
+llm_usage.jsonl
+llm_parsing_error.jsonl
+traces/
+
+**/__pycache__/**
+.DS_Store
+**/.DS_Store
+old
+notebook
+examples/benchmark_params.toml
+**/*/trending.csv

notte_mcp-1.4.4/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: notte-mcp
+Version: 1.4.4
+Summary: The MCP server for Notte
+Author-email: Notte Team  <hello@notte.cc>
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: notte-sdk==v1.4.4
+Requires-Dist: python-dotenv>=1.0.1
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <p>
+    ⚡️ we outperform other web agents in speed, costs and reliability 👉🏼 <a href="https://github.com/nottelabs/open-operator-evals">read more on open-operator-evals</a>
+  </p>
+</div>
+
+<p align="center">
+  <img src="../../docs/logo/bgd.png" alt="Notte Logo" width="100%">
+</p>
+
+# Notte MCP Server
+
+<div align="center">
+  <h1>Notte MCP Server</h1>
+  <p><em>MCP server for all Notte tools in the agentic ecosystem.</em></p>
+  <p><strong>Manage your sessions. Run agents. Take control: observe, scrape, act, authenticate.</strong></p>
+  <hr/>
+</div>
+[The Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) provides a standardized protocol for connecting LLM applications with external tools and data sources. It enables seamless integration between language models and the context they need, whether you're developing an AI-powered IDE, building a chat interface, or designing custom AI workflows.
+
+## Available Tools
+
+### Session Management
+
+| Tool | Description |
+|------|-------------|
+| `notte_start_session` | Start a new cloud browser session |
+| `notte_list_sessions` | List all active browser sessions |
+| `notte_stop_session` | Stop the current session |
+
+### Page Interaction & Scraping
+
+| Tool | Description |
+|------|-------------|
+| `notte_observe` | Observe elements and available actions on the current page |
+| `notte_screenshot` | Take a screenshot of the current page |
+| `notte_scrape` | Extract structured data from the current page |
+| `notte_step` | Execute an action on the current page |
+
+### Agent Operations
+
+| Tool | Description |
+|------|-------------|
+| `notte_operator` | Run a Notte agent to complete a task on any website |
+
+## Getting Started
+
+1. Install the required dependencies:
+```bash
+pip install notte-mcp
+```
+
+2. Set up your environment variables:
+```bash
+export NOTTE_API_KEY="your-api-key"
+```
+
+3. Start the MCP server:
+```bash
+python -m notte_mcp.server
+```
+
+> note: you can also start the server locally using `uv run mcp dev packages/notte-mcp/src/notte_mcp/server.py  --with-editable .`
+
+To use the MCP in cursor or claude computer use, you can use the following json:
+
+```json
+{
+    "mcpServers": {
+        "notte-mcp": {
+            "url": "http://localhost:8000/sse",
+            "env": {
+                "NOTTE_API_KEY": "<your-notte-api-key>"
+            }
+        }
+    }
+}
+```

notte_mcp-1.4.4/README.md

@@ -0,0 +1,78 @@
+<div align="center">
+  <p>
+    ⚡️ we outperform other web agents in speed, costs and reliability 👉🏼 <a href="https://github.com/nottelabs/open-operator-evals">read more on open-operator-evals</a>
+  </p>
+</div>
+
+<p align="center">
+  <img src="../../docs/logo/bgd.png" alt="Notte Logo" width="100%">
+</p>
+
+# Notte MCP Server
+
+<div align="center">
+  <h1>Notte MCP Server</h1>
+  <p><em>MCP server for all Notte tools in the agentic ecosystem.</em></p>
+  <p><strong>Manage your sessions. Run agents. Take control: observe, scrape, act, authenticate.</strong></p>
+  <hr/>
+</div>
+[The Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) provides a standardized protocol for connecting LLM applications with external tools and data sources. It enables seamless integration between language models and the context they need, whether you're developing an AI-powered IDE, building a chat interface, or designing custom AI workflows.
+
+## Available Tools
+
+### Session Management
+
+| Tool | Description |
+|------|-------------|
+| `notte_start_session` | Start a new cloud browser session |
+| `notte_list_sessions` | List all active browser sessions |
+| `notte_stop_session` | Stop the current session |
+
+### Page Interaction & Scraping
+
+| Tool | Description |
+|------|-------------|
+| `notte_observe` | Observe elements and available actions on the current page |
+| `notte_screenshot` | Take a screenshot of the current page |
+| `notte_scrape` | Extract structured data from the current page |
+| `notte_step` | Execute an action on the current page |
+
+### Agent Operations
+
+| Tool | Description |
+|------|-------------|
+| `notte_operator` | Run a Notte agent to complete a task on any website |
+
+## Getting Started
+
+1. Install the required dependencies:
+```bash
+pip install notte-mcp
+```
+
+2. Set up your environment variables:
+```bash
+export NOTTE_API_KEY="your-api-key"
+```
+
+3. Start the MCP server:
+```bash
+python -m notte_mcp.server
+```
+
+> note: you can also start the server locally using `uv run mcp dev packages/notte-mcp/src/notte_mcp/server.py  --with-editable .`
+
+To use the MCP in cursor or claude computer use, you can use the following json:
+
+```json
+{
+    "mcpServers": {
+        "notte-mcp": {
+            "url": "http://localhost:8000/sse",
+            "env": {
+                "NOTTE_API_KEY": "<your-notte-api-key>"
+            }
+        }
+    }
+}
+```

notte_mcp-1.4.4/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "notte-mcp"
+version = "v1.4.4"
+description = "The MCP server for Notte"
+readme = "README.md"
+authors = [
+    { name = "Notte Team ", email = "hello@notte.cc" }
+]
+packages = [
+    { include = "notte_mcp", from = "src" },
+]
+
+
+requires-python = ">=3.11"
+dependencies = [
+    "python-dotenv>=1.0.1",
+    "mcp[cli]>=1.6.0",
+    "notte-sdk==v1.4.4",
+]
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

notte_mcp-1.4.4/src/notte_mcp/__init__.py

@@ -0,0 +1,3 @@
+from notte_core import check_notte_version
+
+__version__ = check_notte_version("notte_mcp")

notte_mcp-1.4.4/src/notte_mcp/server.py

@@ -0,0 +1,157 @@
+import os
+import pathlib
+from collections.abc import Sequence
+from typing import Annotated
+
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP, Image
+from notte_sdk import NotteClient, __version__
+from notte_sdk.types import ObserveResponse, ScrapeResponse, SessionResponse
+
+_ = load_dotenv()
+
+mcp_server_path = pathlib.Path(__file__).absolute()
+session: SessionResponse | None = None
+
+os.environ["NOTTE_MCP_SERVER_PATH"] = str(mcp_server_path)
+
+MAX_AGENT_WAIT_TIME = 120
+
+notte = NotteClient(api_key=os.getenv("NOTTE_API_KEY"))
+
+# Create an MCP server
+mcp = FastMCP(
+    name="Notte MCP Server for Notte Browser Sessions and Web Agents Operators",
+    request_timeout=MAX_AGENT_WAIT_TIME,
+    # TOOD: coment out this line for local testing
+    dependencies=[f"notte-sdk=={__version__}", "mcp[cli]>=1.6.0"],
+)
+
+
+def get_session_id() -> str:
+    global session
+    if session is None:
+        response = notte.sessions.start()
+        session = response
+    return session.session_id
+
+
+@mcp.tool(description="Start a new cloud browser session using Notte")
+def notte_start_session() -> str:
+    """Start a new Notte session"""
+    response = notte.sessions.start()
+    global session
+    session = response
+    return f"Session {session.session_id} started"
+
+
+@mcp.tool(description="List all Notte Cloud Browser active sessions")
+def notte_list_sessions() -> Sequence[SessionResponse]:
+    """List all active Notte sessions"""
+    return notte.sessions.list(only_active=True)
+
+
+@mcp.tool(description="Stop the current Notte session")
+def notte_stop_session() -> str:
+    """Stop the current Notte session"""
+    session_id = get_session_id()
+    _ = notte.sessions.stop(session_id=session_id)
+    global session
+    session = None
+    return f"Session {session_id} stopped"
+
+
+@mcp.tool(
+    description="Takes a screenshot of the current page. Use this tool to learn where you are on the page when navigating. Only use this tool when the other tools are not sufficient to get the information you need."
+)
+def notte_screenshot() -> Image:
+    """Takes a screenshot of the current page"""
+    session_id = get_session_id()
+    response = notte.sessions.page.observe(session_id=session_id)
+    assert response.screenshot is not None
+    return Image(
+        data=response.screenshot,
+        format="png",
+    )
+
+
+@mcp.tool(
+    description="Observes elements on the web page. Use this tool to observe elements that you can later use in an action. Use observe instead of extract when dealing with actionable (interactable) elements rather than text."
+)
+def notte_observe(
+    url: Annotated[
+        str | None,
+        "The URL of the webpage to observe. If not provided, the current page in the Notte Browser Session will be observed.",
+    ] = None,
+) -> ObserveResponse:
+    """Observe the current page and the available actions on it"""
+    session_id = get_session_id()
+    response = notte.sessions.page.observe(session_id=session_id, url=url)
+    response.screenshot = None
+    assert session is not None
+    return ObserveResponse.from_obs(response, session=session)
+
+
+@mcp.tool(description="Scrape the current page data")
+def notte_scrape(
+    url: Annotated[
+        str | None,
+        "The URL of the webpage scrape. If not provided, the current page in the Notte Browser Session will be scraped.",
+    ] = None,
+    instructions: Annotated[
+        str | None, "Additional instructions to use for the scrape (i.e specific fields or information to extract)."
+    ] = None,
+) -> ScrapeResponse:
+    """Scrape the current page data"""
+    session_id = get_session_id()
+    data = notte.sessions.page.scrape(session_id=session_id, url=url, instructions=instructions, use_llm=True)
+    assert session is not None
+    return ScrapeResponse(
+        data=data,
+        session=session,
+    )
+
+
+@mcp.tool(
+    description="Take an action on the current page. Use `notte_observe` first to list the available actions. Then use this tool to take an action. Don't hallucinate any action not listed in the observation."
+)
+def notte_step(
+    action_id: Annotated[str, "The ID of the action to execute. Use `notte_observe` to list the available actions."],
+    value: Annotated[
+        str | None,
+        "The value to input for form actions. Only to be provider for interactions actions (i.e ID starts with `I`, e.g. `I0`, `I1`, etc.)",
+    ] = None,
+) -> ObserveResponse:
+    """Take an action on the current page"""
+    session_id = get_session_id()
+    obs = notte.sessions.page.step(session_id=session_id, action_id=action_id, value=value)
+    obs.screenshot = None
+    assert session is not None
+    return ObserveResponse.from_obs(obs, session=session)
+
+
+@mcp.tool(description="Run an `Notte` agent/operator to complete a given task on any website")
+def notte_operator(
+    task: Annotated[str, "The task to complete"],
+    url: Annotated[str | None, "The URL to complete the task on (optional)"] = None,
+    vizualize_in_browser: Annotated[
+        bool,
+        "Whether to visualize the agent's work in the browser (should only be set to True if explicitely requested by the user otherwise set it to False by default)",
+    ] = False,
+) -> str:
+    """Run an agent asynchronously"""
+    agent = notte.agents.start(task=task, url=url)
+    if vizualize_in_browser:
+        notte.sessions.viewer(session_id=agent.session_id)
+    # wait for the agent to finish
+    response = notte.agents.wait(agent.agent_id)
+    if response.success:
+        assert response.answer is not None
+        return response.answer
+    else:
+        return "Failed to run agent. Try to be better specify the task and url."
+
+
+if __name__ == "__main__":
+    # mcp.run(transport="sse")
+    mcp.run(transport="stdio")