crewai-webzio 0.1.0__tar.gz

crewai_webzio-0.1.0/.env.example

@@ -0,0 +1,2 @@
+WEBZ_API_TOKEN=
+WEBZ_MCP_URL=https://news-search-mcp.webz.io/mcp

crewai_webzio-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+venv/
+.idea/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+langchain_tests/
+node_modules/
+*.db
+*.tsbuildinfo
+*.tgz

crewai_webzio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webz.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crewai_webzio-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: crewai-webzio
+Version: 0.1.0
+Summary: CrewAI tools for Webz.io News Search - global news in natural language with semantic ranking and rich filters
+Project-URL: Homepage, https://news-search-mcp.webz.io
+Project-URL: Documentation, https://docs.webz.io/docs/webz/news-search-api-mcp
+Project-URL: Repository, https://github.com/Webhose/webz-news-search
+Project-URL: Issues, https://github.com/Webhose/webz-news-search/issues
+Author-email: "Webz.io" <support@webz.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crewai,mcp,news,search,webz,webzio
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: crewai-tools[mcp]>=0.40.0
+Requires-Dist: crewai>=0.80.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crewai-webzio
+
+**Search global news with [Webz.io](https://webz.io) from [CrewAI](https://crewai.com) agents — in natural language, with the most relevant articles first.**
+
+[Webz.io News Search](https://docs.webz.io/docs/webz/news-search-api-mcp) covers news and current events from sources worldwide. Ask a question in plain language, narrow results with filters (language, country, date, sentiment, domain, ticker, and more), and get back focused article excerpts with titles, URLs, and metadata.
+
+Use this package with CrewAI agents, or construct the tool directly to verify MCP connectivity.
+
+## What you get
+
+- **Natural-language search** — no keyword hacking. Example: `"EU AI Act enforcement updates"` or `"How is Tesla stock reacting to earnings?"`
+- **Worldwide coverage** — semantic search over Webz.io's global news index.
+- **Rich filters** — language, country, days, sentiment, domain, ticker, person, organization, topic, and more. See the [MCP tool reference](https://docs.webz.io/docs/webz/news-search-api-mcp#tool-reference).
+- **Live schema** — filters are loaded from the hosted MCP server (`tools/list`). New Webz filters appear automatically, without republishing this package.
+- **CrewAI tool** — pass `WebzioNewsSearchTool(...)` to `Agent(tools=[...])`.
+
+## Install
+
+```bash
+pip install crewai-webzio
+export WEBZ_API_TOKEN="your-webz-api-token"
+```
+
+Get a token from your [Webz.io dashboard](https://webz.io) (same token as the News Search API).
+
+Requires CrewAI with MCP support (`crewai-tools[mcp]`, installed automatically).
+
+Full setup and client options: [MCP Server docs](https://docs.webz.io/docs/webz/news-search-api-mcp).
+
+## With a CrewAI agent
+
+```python
+import os
+
+from crewai import Agent, Crew, Task
+from crewai_webzio import WebzioNewsSearchTool
+
+with WebzioNewsSearchTool(api_token=os.environ["WEBZ_API_TOKEN"]) as news_tool:
+    researcher = Agent(
+        role="Research Analyst",
+        goal="Find recent news on any topic",
+        backstory="Expert researcher with access to Webz.io news search.",
+        tools=[news_tool],
+        verbose=True,
+    )
+
+    research_task = Task(
+        description=(
+            "Search Webz news for recent Nvidia supply-chain risk coverage "
+            "and summarize with sources."
+        ),
+        expected_output="A summary with headline, publisher, and URL for each article.",
+        agent=researcher,
+    )
+
+    crew = Crew(agents=[researcher], tasks=[research_task], verbose=True)
+    print(crew.kickoff())
+```
+
+Use the tool as a context manager (or call `stop()` when done) to shut down the MCP session.
+
+## Direct search (no agent required)
+
+```bash
+export WEBZ_API_TOKEN="your-token"
+python examples/run_news_search.py
+```
+
+```python
+from crewai_webzio import WebzioNewsSearchTool
+
+with WebzioNewsSearchTool() as tool:
+    print(sorted(tool.arg_names))  # live filters from MCP tools/list
+    print(tool._run(query="EU AI regulation", k=5, days=30))
+```
+
+## Using Webz via MCP (no package install)
+
+CrewAI can connect to the hosted MCP server directly:
+
+```python
+from crewai import Agent
+from crewai.mcp import MCPServerHTTP
+
+agent = Agent(
+    role="News Researcher",
+    goal="Find and summarize current news",
+    mcps=[
+        MCPServerHTTP(
+            url="https://news-search-mcp.webz.io/mcp",
+            headers={"Authorization": "Bearer YOUR_WEBZ_API_TOKEN"},
+        ),
+    ],
+)
+```
+
+## How it works
+
+This package wraps CrewAI's [`MCPServerAdapter`](https://docs.crewai.com/en/mcp/overview) around the hosted Webz News Search MCP server at `https://news-search-mcp.webz.io/mcp`. Each tool call runs a regular News Search API request with your token (same credits and rate limits). Filter fields are not hardcoded — the tool schema comes from the live server.
+
+## Configuration
+
+| Name | Default | Purpose |
+| --- | --- | --- |
+| `WEBZ_API_TOKEN` | required | Webz API token from the dashboard |
+| `WEBZ_MCP_URL` | `https://news-search-mcp.webz.io/mcp` | Override for local MCP testing |
+
+You can also pass `api_token=` and `mcp_url=` to `WebzioNewsSearchTool()`.
+
+## Links
+
+- [Webz.io](https://webz.io)
+- [News Search MCP documentation](https://docs.webz.io/docs/webz/news-search-api-mcp)
+- [MCP server landing page](https://news-search-mcp.webz.io)
+- [News Search API filters](https://docs.webz.io/docs/webz/news-search-api-filters)
+- [CrewAI MCP overview](https://docs.crewai.com/en/mcp/overview)
+- [GitHub](https://github.com/Webhose/webz-news-search)

crewai_webzio-0.1.0/PUBLISHING.md

@@ -0,0 +1,36 @@
+# Publishing crewai-webzio to PyPI
+
+## Prerequisites
+
+- PyPI account and API token with upload scope
+- `twine` installed (`pip install twine build`)
+
+## Build
+
+```bash
+cd packages/crewai
+python -m pip install build
+python -m build
+```
+
+Artifacts land in `dist/`:
+
+- `crewai_webzio-0.1.0-py3-none-any.whl`
+- `crewai_webzio-0.1.0.tar.gz`
+
+## Upload
+
+```bash
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-xxxxxxxx
+python -m twine upload dist/crewai_webzio-*
+```
+
+Or use `uv publish` if configured.
+
+## Verify
+
+```bash
+pip install crewai-webzio
+python -c "from crewai_webzio import WebzioNewsSearchTool; print(WebzioNewsSearchTool)"
+```

crewai_webzio-0.1.0/README.md

@@ -0,0 +1,117 @@
+# crewai-webzio
+
+**Search global news with [Webz.io](https://webz.io) from [CrewAI](https://crewai.com) agents — in natural language, with the most relevant articles first.**
+
+[Webz.io News Search](https://docs.webz.io/docs/webz/news-search-api-mcp) covers news and current events from sources worldwide. Ask a question in plain language, narrow results with filters (language, country, date, sentiment, domain, ticker, and more), and get back focused article excerpts with titles, URLs, and metadata.
+
+Use this package with CrewAI agents, or construct the tool directly to verify MCP connectivity.
+
+## What you get
+
+- **Natural-language search** — no keyword hacking. Example: `"EU AI Act enforcement updates"` or `"How is Tesla stock reacting to earnings?"`
+- **Worldwide coverage** — semantic search over Webz.io's global news index.
+- **Rich filters** — language, country, days, sentiment, domain, ticker, person, organization, topic, and more. See the [MCP tool reference](https://docs.webz.io/docs/webz/news-search-api-mcp#tool-reference).
+- **Live schema** — filters are loaded from the hosted MCP server (`tools/list`). New Webz filters appear automatically, without republishing this package.
+- **CrewAI tool** — pass `WebzioNewsSearchTool(...)` to `Agent(tools=[...])`.
+
+## Install
+
+```bash
+pip install crewai-webzio
+export WEBZ_API_TOKEN="your-webz-api-token"
+```
+
+Get a token from your [Webz.io dashboard](https://webz.io) (same token as the News Search API).
+
+Requires CrewAI with MCP support (`crewai-tools[mcp]`, installed automatically).
+
+Full setup and client options: [MCP Server docs](https://docs.webz.io/docs/webz/news-search-api-mcp).
+
+## With a CrewAI agent
+
+```python
+import os
+
+from crewai import Agent, Crew, Task
+from crewai_webzio import WebzioNewsSearchTool
+
+with WebzioNewsSearchTool(api_token=os.environ["WEBZ_API_TOKEN"]) as news_tool:
+    researcher = Agent(
+        role="Research Analyst",
+        goal="Find recent news on any topic",
+        backstory="Expert researcher with access to Webz.io news search.",
+        tools=[news_tool],
+        verbose=True,
+    )
+
+    research_task = Task(
+        description=(
+            "Search Webz news for recent Nvidia supply-chain risk coverage "
+            "and summarize with sources."
+        ),
+        expected_output="A summary with headline, publisher, and URL for each article.",
+        agent=researcher,
+    )
+
+    crew = Crew(agents=[researcher], tasks=[research_task], verbose=True)
+    print(crew.kickoff())
+```
+
+Use the tool as a context manager (or call `stop()` when done) to shut down the MCP session.
+
+## Direct search (no agent required)
+
+```bash
+export WEBZ_API_TOKEN="your-token"
+python examples/run_news_search.py
+```
+
+```python
+from crewai_webzio import WebzioNewsSearchTool
+
+with WebzioNewsSearchTool() as tool:
+    print(sorted(tool.arg_names))  # live filters from MCP tools/list
+    print(tool._run(query="EU AI regulation", k=5, days=30))
+```
+
+## Using Webz via MCP (no package install)
+
+CrewAI can connect to the hosted MCP server directly:
+
+```python
+from crewai import Agent
+from crewai.mcp import MCPServerHTTP
+
+agent = Agent(
+    role="News Researcher",
+    goal="Find and summarize current news",
+    mcps=[
+        MCPServerHTTP(
+            url="https://news-search-mcp.webz.io/mcp",
+            headers={"Authorization": "Bearer YOUR_WEBZ_API_TOKEN"},
+        ),
+    ],
+)
+```
+
+## How it works
+
+This package wraps CrewAI's [`MCPServerAdapter`](https://docs.crewai.com/en/mcp/overview) around the hosted Webz News Search MCP server at `https://news-search-mcp.webz.io/mcp`. Each tool call runs a regular News Search API request with your token (same credits and rate limits). Filter fields are not hardcoded — the tool schema comes from the live server.
+
+## Configuration
+
+| Name | Default | Purpose |
+| --- | --- | --- |
+| `WEBZ_API_TOKEN` | required | Webz API token from the dashboard |
+| `WEBZ_MCP_URL` | `https://news-search-mcp.webz.io/mcp` | Override for local MCP testing |
+
+You can also pass `api_token=` and `mcp_url=` to `WebzioNewsSearchTool()`.
+
+## Links
+
+- [Webz.io](https://webz.io)
+- [News Search MCP documentation](https://docs.webz.io/docs/webz/news-search-api-mcp)
+- [MCP server landing page](https://news-search-mcp.webz.io)
+- [News Search API filters](https://docs.webz.io/docs/webz/news-search-api-filters)
+- [CrewAI MCP overview](https://docs.crewai.com/en/mcp/overview)
+- [GitHub](https://github.com/Webhose/webz-news-search)

crewai_webzio-0.1.0/crewai_webzio/__init__.py

@@ -0,0 +1,29 @@
+from crewai_webzio.consts import (
+    DEFAULT_MCP_URL,
+    MCP_TRANSPORT,
+    MCP_URL_ENV_NAME,
+    PREFERRED_TOOL_NAME,
+    TOKEN_ENV_NAME,
+)
+from crewai_webzio.tool import (
+    WebzConfigError,
+    WebzioNewsSearchTool,
+    build_server_params,
+    pick_news_search_tool,
+    resolve_api_token,
+    resolve_mcp_url,
+)
+
+__all__ = [
+    "DEFAULT_MCP_URL",
+    "MCP_TRANSPORT",
+    "MCP_URL_ENV_NAME",
+    "PREFERRED_TOOL_NAME",
+    "TOKEN_ENV_NAME",
+    "WebzConfigError",
+    "WebzioNewsSearchTool",
+    "build_server_params",
+    "pick_news_search_tool",
+    "resolve_api_token",
+    "resolve_mcp_url",
+]

crewai_webzio-0.1.0/crewai_webzio/consts.py

@@ -0,0 +1,5 @@
+DEFAULT_MCP_URL = "https://news-search-mcp.webz.io/mcp"
+TOKEN_ENV_NAME = "WEBZ_API_TOKEN"
+MCP_URL_ENV_NAME = "WEBZ_MCP_URL"
+PREFERRED_TOOL_NAME = "news_search_by_webz"
+MCP_TRANSPORT = "streamable-http"

crewai_webzio-0.1.0/crewai_webzio/tool.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import os
+from types import TracebackType
+from typing import Any
+
+from crewai.tools import BaseTool, EnvVar
+from crewai_tools import MCPServerAdapter
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+from crewai_webzio.consts import (
+    DEFAULT_MCP_URL,
+    MCP_TRANSPORT,
+    MCP_URL_ENV_NAME,
+    PREFERRED_TOOL_NAME,
+    TOKEN_ENV_NAME,
+)
+
+
+class WebzConfigError(ValueError):
+    """Raised when the Webz MCP client cannot be configured or loaded."""
+
+
+def resolve_api_token(api_token: str | None = None) -> str:
+    token = (api_token or os.getenv(TOKEN_ENV_NAME) or "").strip()
+    if not token:
+        raise WebzConfigError(
+            f"missing Webz API token. set {TOKEN_ENV_NAME} or pass api_token."
+        )
+    return token
+
+
+def resolve_mcp_url(mcp_url: str | None = None) -> str:
+    url = (mcp_url or os.getenv(MCP_URL_ENV_NAME) or DEFAULT_MCP_URL).strip()
+    if not url:
+        raise WebzConfigError("missing MCP url.")
+    return url.rstrip("/")
+
+
+def build_server_params(
+    api_token: str | None = None,
+    *,
+    mcp_url: str | None = None,
+) -> dict[str, Any]:
+    token = resolve_api_token(api_token)
+    url = resolve_mcp_url(mcp_url)
+    return {
+        "url": url,
+        "transport": MCP_TRANSPORT,
+        "headers": {"Authorization": f"Bearer {token}"},
+    }
+
+
+def pick_news_search_tool(tools: list[BaseTool]) -> BaseTool:
+    if not tools:
+        raise WebzConfigError("MCP server returned no tools.")
+    for tool in tools:
+        if tool.name == PREFERRED_TOOL_NAME:
+            return tool
+    if len(tools) == 1:
+        return tools[0]
+    names = ", ".join(tool.name for tool in tools)
+    raise WebzConfigError(
+        f"MCP server did not expose {PREFERRED_TOOL_NAME}. available tools: {names}"
+    )
+
+
+class WebzioNewsSearchToolSchema(BaseModel):
+    """Minimal static schema; replaced at init with the live MCP schema."""
+
+    model_config = ConfigDict(extra="allow")
+
+    query: str = Field(..., description="Natural-language news search query")
+
+
+class WebzioNewsSearchTool(BaseTool):
+    """CrewAI tool that exposes Webz.io contextual news search via the hosted MCP server.
+
+    Filter fields are loaded live from MCP ``tools/list``. New server filters appear
+    automatically at runtime without republishing this package.
+
+    Use as a context manager or call ``stop()`` when done to shut down the MCP session::
+
+        with WebzioNewsSearchTool() as tool:
+            agent = Agent(..., tools=[tool])
+    """
+
+    name: str = PREFERRED_TOOL_NAME
+    description: str = (
+        "Search global news with Webz.io. Returns article excerpts with titles, "
+        "URLs, and metadata. Filter by language, country, date, sentiment, domain, "
+        "ticker, and more."
+    )
+    args_schema: type[BaseModel] = WebzioNewsSearchToolSchema
+    package_dependencies: list[str] = Field(
+        default_factory=lambda: ["crewai-tools[mcp]"]
+    )
+    env_vars: list[EnvVar] = Field(
+        default_factory=lambda: [
+            EnvVar(
+                name=TOKEN_ENV_NAME,
+                description="Webz.io API token from the dashboard",
+                required=True,
+            ),
+            EnvVar(
+                name=MCP_URL_ENV_NAME,
+                description="Override MCP endpoint for testing",
+                required=False,
+            ),
+        ]
+    )
+
+    _adapter: MCPServerAdapter | None = PrivateAttr(default=None)
+    _live_tool: BaseTool | None = PrivateAttr(default=None)
+
+    def __init__(
+        self,
+        api_token: str | None = None,
+        *,
+        mcp_url: str | None = None,
+        connect_timeout: int = 30,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._adapter = MCPServerAdapter(
+            build_server_params(api_token, mcp_url=mcp_url),
+            PREFERRED_TOOL_NAME,
+            connect_timeout=connect_timeout,
+        )
+        self._live_tool = pick_news_search_tool(list(self._adapter.tools))
+        self.args_schema = self._live_tool.args_schema
+        self.description = self._live_tool.description
+
+    @property
+    def arg_names(self) -> list[str]:
+        """Live argument names from the MCP tool schema."""
+        return list(self.args_schema.model_fields.keys())
+
+    def _run(self, **kwargs: Any) -> str:
+        if self._live_tool is None:
+            raise WebzConfigError("MCP news search tool is not initialized.")
+        result = self._live_tool._run(**kwargs)
+        return str(result)
+
+    def stop(self) -> None:
+        """Stop the underlying MCP server connection."""
+        if self._adapter is not None:
+            self._adapter.stop()
+            self._adapter = None
+            self._live_tool = None
+
+    def __enter__(self) -> WebzioNewsSearchTool:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.stop()

crewai_webzio-0.1.0/examples/run_news_search.py

@@ -0,0 +1,40 @@
+"""
+Construct a WebzioNewsSearchTool and run one search against the hosted MCP server.
+
+Usage:
+  export WEBZ_API_TOKEN="your-token"
+  python examples/run_news_search.py
+
+Or pass the token in code with WebzioNewsSearchTool(api_token="...").
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from crewai_webzio import WebzioNewsSearchTool
+
+QUERY = "recent developments on EU AI regulation"
+
+
+def main() -> None:
+    token = os.getenv("WEBZ_API_TOKEN")
+    with (
+        WebzioNewsSearchTool(api_token=token)
+        if token
+        else WebzioNewsSearchTool()
+    ) as tool:
+        print("tool name:", tool.name)
+        print("live args from MCP tools/list:", sorted(tool.arg_names))
+        print("---")
+        print(tool._run(query=QUERY, k=3), end="\n\n")
+        print("SUCCESS ! tool is ready for Agent(tools=[tool])")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        print(f"search failed: {exc}", file=sys.stderr)
+        raise SystemExit(1)

crewai_webzio-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-webzio"
+version = "0.1.0"
+description = "CrewAI tools for Webz.io News Search - global news in natural language with semantic ranking and rich filters"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Webz.io", email = "support@webz.io" },
+]
+keywords = ["crewai", "webz", "webzio", "news", "mcp", "search"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "crewai>=0.80.0",
+    "crewai-tools[mcp]>=0.40.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.urls]
+Homepage = "https://news-search-mcp.webz.io"
+Documentation = "https://docs.webz.io/docs/webz/news-search-api-mcp"
+Repository = "https://github.com/Webhose/webz-news-search"
+Issues = "https://github.com/Webhose/webz-news-search/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["crewai_webzio"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

crewai_webzio-0.1.0/tests/test_live.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from crewai_webzio import WebzioNewsSearchTool
+from crewai_webzio.consts import PREFERRED_TOOL_NAME
+
+pytestmark = pytest.mark.skipif(
+    not os.getenv("WEBZ_API_TOKEN"),
+    reason="WEBZ_API_TOKEN is not set",
+)
+
+
+def test_live_tool_discovers_news_search_schema() -> None:
+    with WebzioNewsSearchTool() as tool:
+        assert tool.name == PREFERRED_TOOL_NAME
+        assert "query" in tool.arg_names
+        assert len(tool.arg_names) > 1
+
+
+def test_live_tool_runs_news_search() -> None:
+    with WebzioNewsSearchTool() as tool:
+        result = tool._run(query="EU AI regulation", k=1)
+        assert isinstance(result, str)
+        assert len(result) > 0

crewai_webzio-0.1.0/tests/test_tool.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from crewai_webzio.consts import (
+    DEFAULT_MCP_URL,
+    MCP_TRANSPORT,
+    PREFERRED_TOOL_NAME,
+    TOKEN_ENV_NAME,
+)
+from crewai_webzio.tool import (
+    WebzConfigError,
+    WebzioNewsSearchTool,
+    build_server_params,
+    pick_news_search_tool,
+    resolve_api_token,
+    resolve_mcp_url,
+)
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+TOOL_SOURCE = (PACKAGE_ROOT / "crewai_webzio" / "tool.py").read_text(encoding="utf-8")
+CONSTS_SOURCE = (PACKAGE_ROOT / "crewai_webzio" / "consts.py").read_text(encoding="utf-8")
+
+FILTER_NAMES_OWNED_BY_MCP = (
+    "allow_all_dates",
+    "exclude_domain",
+    "domain_rank_gte",
+    "domain_rank_lte",
+    "trust_category",
+    "political_bias",
+    "min_similarity",
+    "allow_multiple_chunks_per_article",
+)
+
+
+class LiveArgsSchema(BaseModel):
+    query: str = Field(..., description="Search query")
+    k: int = Field(default=10, description="Number of results")
+    extra_filter: str = Field(default="x", description="From MCP server")
+
+
+class FakeLiveTool(BaseTool):
+    name: str = PREFERRED_TOOL_NAME
+    description: str = "Live MCP news search tool"
+    args_schema: type[BaseModel] = LiveArgsSchema
+
+    def _run(self, **kwargs: object) -> str:
+        return f"result:{kwargs.get('query')}"
+
+
+class FakeMcpAdapter:
+    def __init__(
+        self,
+        serverparams: dict,
+        *tool_names: str,
+        connect_timeout: int = 30,
+    ) -> None:
+        self.serverparams = serverparams
+        self.tool_names = tool_names
+        self.connect_timeout = connect_timeout
+        self._stopped = False
+        self.tools = [FakeLiveTool()]
+
+    def stop(self) -> None:
+        self._stopped = True
+
+
+def test_resolve_api_token_requires_value(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv(TOKEN_ENV_NAME, raising=False)
+    with pytest.raises(WebzConfigError, match="missing Webz API token"):
+        resolve_api_token()
+
+
+def test_resolve_api_token_prefers_argument(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(TOKEN_ENV_NAME, "from-env")
+    assert resolve_api_token(" from-arg ") == "from-arg"
+
+
+def test_resolve_mcp_url_default_and_override(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("WEBZ_MCP_URL", raising=False)
+    assert resolve_mcp_url() == DEFAULT_MCP_URL
+    assert resolve_mcp_url("https://localhost:8765/mcp/") == "https://localhost:8765/mcp"
+
+
+def test_build_server_params_uses_bearer_and_streamable_http() -> None:
+    params = build_server_params("secret-token", mcp_url="https://example.test/mcp")
+    assert params["url"] == "https://example.test/mcp"
+    assert params["transport"] == MCP_TRANSPORT
+    assert params["headers"]["Authorization"] == "Bearer secret-token"
+
+
+def test_pick_news_search_tool_prefers_named_tool() -> None:
+    preferred = SimpleNamespace(name=PREFERRED_TOOL_NAME)
+    other = SimpleNamespace(name="other_tool")
+    assert pick_news_search_tool([other, preferred]) is preferred  # type: ignore[arg-type]
+
+
+def test_pick_news_search_tool_falls_back_to_single_tool() -> None:
+    only = SimpleNamespace(name="whatever_the_server_exposes")
+    assert pick_news_search_tool([only]) is only  # type: ignore[arg-type]
+
+
+def test_pick_news_search_tool_errors_when_preferred_missing_among_many() -> None:
+    with pytest.raises(WebzConfigError, match="did not expose"):
+        pick_news_search_tool(
+            [SimpleNamespace(name="alpha"), SimpleNamespace(name="beta")]  # type: ignore[list-item]
+        )
+
+
+@patch("crewai_webzio.tool.MCPServerAdapter", FakeMcpAdapter)
+def test_webzio_news_search_tool_loads_live_schema_and_delegates_run() -> None:
+    tool = WebzioNewsSearchTool(api_token="tok", mcp_url="https://example.test/mcp")
+    try:
+        assert tool.name == PREFERRED_TOOL_NAME
+        assert "query" in tool.arg_names
+        assert "extra_filter" in tool.arg_names
+        assert tool.description == "Live MCP news search tool"
+        assert tool._run(query="EU AI", k=3) == "result:EU AI"
+    finally:
+        tool.stop()
+
+
+@patch("crewai_webzio.tool.MCPServerAdapter", FakeMcpAdapter)
+def test_webzio_news_search_tool_context_manager_stops_adapter() -> None:
+    with WebzioNewsSearchTool(api_token="tok") as tool:
+        assert tool._adapter is not None
+        adapter = tool._adapter
+    assert adapter._stopped is True
+    assert tool._adapter is None
+
+
+def test_wrapper_source_does_not_hardcode_mcp_filters() -> None:
+    combined = TOOL_SOURCE + CONSTS_SOURCE
+    for name in FILTER_NAMES_OWNED_BY_MCP:
+        assert name not in combined, f"wrapper must not hardcode MCP filter {name}"
+
+
+def test_public_exports() -> None:
+    import crewai_webzio
+
+    for name in (
+        "WebzioNewsSearchTool",
+        "WebzConfigError",
+        "DEFAULT_MCP_URL",
+        "TOKEN_ENV_NAME",
+        "build_server_params",
+        "resolve_api_token",
+        "resolve_mcp_url",
+    ):
+        assert hasattr(crewai_webzio, name)

crewai_webzio-0.1.0/upstream/README.md

@@ -0,0 +1,44 @@
+# Upstream contribution to crewAIInc/crewAI
+
+This directory contains files ready to copy into a PR against [crewAIInc/crewAI](https://github.com/crewAIInc/crewAI).
+
+## PR checklist
+
+1. Copy `lib/crewai-tools/src/crewai_tools/tools/webzio_tools/webzio_news_search_tool.py` into the fork.
+2. Add to `lib/crewai-tools/src/crewai_tools/tools/__init__.py`:
+   ```python
+   from crewai_tools.tools.webzio_tools.webzio_news_search_tool import (
+       WebzioNewsSearchTool,
+   )
+   ```
+   and add `"WebzioNewsSearchTool"` to `__all__`.
+3. Add to `lib/crewai-tools/src/crewai_tools/__init__.py` the same import and export.
+4. Copy `lib/crewai-tools/tests/tools/webzio_news_search_tool_test.py`.
+5. Copy `docs/en/tools/search-research/webzionewssearchtool.mdx`.
+6. Add a card to `docs/en/tools/search-research/overview.mdx` (Search & Research section).
+7. Register the page in the docs nav (`docs.json` or equivalent Mintlify config).
+8. Regenerate tool specs:
+   ```bash
+   cd lib/crewai-tools
+   python -m crewai_tools.generate_tool_specs
+   ```
+9. Run tests:
+   ```bash
+   pytest lib/crewai-tools/tests/tools/webzio_news_search_tool_test.py
+   ```
+
+No new vendor SDK dependency is required — the tool uses the existing `mcp` extra via `MCPServerAdapter`.
+
+## Suggested PR title
+
+`feat(tools): add WebzioNewsSearchTool for Webz.io news search via MCP`
+
+## Suggested PR description
+
+- Adds `WebzioNewsSearchTool` wrapping the hosted Webz News Search MCP server
+- Filter schema loaded live from MCP `tools/list` (not hardcoded)
+- Auth via `WEBZ_API_TOKEN` (Bearer) and optional `WEBZ_MCP_URL`
+- Docs page under Search & Research, modeled on ExaSearchTool
+- Unit tests mock `MCPServerAdapter` (no live token in CI)
+
+Maintained by Webz.io. Standalone PyPI package: [crewai-webzio](https://pypi.org/project/crewai-webzio/).

crewai_webzio-0.1.0/upstream/docs/en/tools/search-research/overview-card-snippet.mdx

@@ -0,0 +1,3 @@
+  <Card title="Webzio News Search" icon="newspaper" href="/en/tools/search-research/webzionewssearchtool">
+    Webz.io contextual news search with live MCP filters
+  </Card>

crewai_webzio-0.1.0/upstream/docs/en/tools/search-research/webzionewssearchtool.mdx

@@ -0,0 +1,135 @@
+---
+title: Webzio News Search Tool
+description: Search global news with Webz.io from CrewAI agents. Semantic ranking, rich filters, and live MCP schemas.
+icon: newspaper
+---
+
+# Webzio News Search Tool
+
+> Search global news with [Webz.io](https://webz.io), the contextual news search API. Get token-efficient article excerpts with titles, URLs, and metadata.
+
+The `WebzioNewsSearchTool` lets CrewAI agents search news and current events using [Webz.io News Search](https://docs.webz.io/docs/webz/news-search-api-mcp). It returns the most relevant articles for any query, with rich filters loaded live from the hosted MCP server.
+
+## Installation
+
+Install the CrewAI tools package with MCP support:
+
+```shell
+pip install 'crewai[tools]'
+```
+
+## Environment Variables
+
+Set your Webz API token as an environment variable:
+
+```bash
+export WEBZ_API_TOKEN='your_webz_api_token'
+```
+
+<Note>
+  The environment variable name is `WEBZ_API_TOKEN` (not `WEBZ_API_KEY`). Get an API key from the [Webz.io dashboard](https://webz.io).
+</Note>
+
+## Example Usage
+
+Here's how to use the `WebzioNewsSearchTool` within a CrewAI agent:
+
+```python
+import os
+from crewai import Agent, Task, Crew
+from crewai_tools import WebzioNewsSearchTool
+
+with WebzioNewsSearchTool(api_token=os.environ["WEBZ_API_TOKEN"]) as news_tool:
+    researcher = Agent(
+        role="Research Analyst",
+        goal="Find recent news on any topic",
+        backstory="Expert researcher with access to Webz.io news search.",
+        tools=[news_tool],
+        verbose=True,
+    )
+
+    research_task = Task(
+        description="Find the top 3 recent breakthroughs in quantum computing.",
+        expected_output="A summary of the top 3 breakthroughs with source URLs.",
+        agent=researcher,
+    )
+
+    crew = Crew(agents=[researcher], tasks=[research_task], verbose=True)
+    result = crew.kickoff()
+    print(result)
+```
+
+Use the tool as a context manager (or call `stop()` when done) to shut down the MCP session.
+
+## Configuration Options
+
+The `WebzioNewsSearchTool` accepts the following parameters during initialization:
+
+* `api_token` (str, optional): Your Webz API token. Falls back to the `WEBZ_API_TOKEN` environment variable if not provided.
+* `mcp_url` (str, optional): Custom MCP server URL. Falls back to the `WEBZ_MCP_URL` environment variable, then `https://news-search-mcp.webz.io/mcp`.
+* `connect_timeout` (int, optional): Connection timeout in seconds (default: `30`).
+
+When calling the tool (or when an agent invokes it), filter parameters are loaded live from MCP `tools/list`. Common parameters include:
+
+* `query` (str): **Required**. Natural-language search query.
+* `k` (int, optional): Number of results (1–100, default 10).
+* `days` (int, optional): Lookback window in days.
+* `language` (list[str], optional): e.g. `["english"]`.
+* `country` (list[str], optional): ISO-2 codes, e.g. `["US", "GB"]`.
+* `sentiment` (str, optional): `positive`, `negative`, or `neutral`.
+* `ticker` (list[str], optional): Stock symbols, e.g. `["NVDA"]`.
+* `domain` / `exclude_domain` (list[str], optional): Restrict or exclude publishers.
+
+For the full filter reference, see the [Webz MCP tool reference](https://docs.webz.io/docs/webz/news-search-api-mcp#tool-reference).
+
+## Advanced Usage
+
+For filtered news research, steer the agent in the task description:
+
+```python
+research_task = Task(
+    description=(
+        "Search Webz news for analyst reaction to Nvidia earnings. "
+        "Use ticker NVDA, the last 7 days, English only, and limit to 5 results."
+    ),
+    expected_output="Headline, publisher, and URL for each article.",
+    agent=researcher,
+)
+```
+
+## Using Webz via MCP
+
+You can also connect your agent to the hosted Webz MCP server directly:
+
+```python
+from crewai import Agent
+from crewai.mcp import MCPServerHTTP
+
+agent = Agent(
+    role="Research Analyst",
+    goal="Find and analyze news on the web",
+    backstory="Expert researcher with access to Webz news search",
+    mcps=[
+        MCPServerHTTP(
+            url="https://news-search-mcp.webz.io/mcp",
+            headers={"Authorization": "Bearer YOUR_WEBZ_API_TOKEN"},
+        ),
+    ],
+)
+```
+
+Get your API key from the [Webz.io dashboard](https://webz.io). For more on MCP in CrewAI, see the [MCP overview](/en/mcp/overview).
+
+## Features
+
+* **Natural-Language Search**: Ask questions in plain language, not keywords
+* **Global Coverage**: Semantic search over Webz.io's worldwide news index
+* **Rich Filters**: Language, country, date, sentiment, domain, ticker, and more
+* **Live Schema**: New filters ship with the MCP server — no package update required
+* **Token-Efficient Excerpts**: Focused article snippets with titles and URLs
+
+## Resources
+
+* [Webz.io News Search MCP documentation](https://docs.webz.io/docs/webz/news-search-api-mcp)
+* [Webz.io dashboard](https://webz.io)
+* [Standalone PyPI package: crewai-webzio](https://pypi.org/project/crewai-webzio/)

crewai_webzio-0.1.0/upstream/lib/crewai-tools/src/crewai_tools/tools/webzio_tools/webzio_news_search_tool.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import os
+from types import TracebackType
+from typing import Any
+
+from crewai.tools import BaseTool, EnvVar
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+from crewai_tools.adapters.mcp_adapter import MCPServerAdapter
+
+DEFAULT_MCP_URL = "https://news-search-mcp.webz.io/mcp"
+TOKEN_ENV_NAME = "WEBZ_API_TOKEN"
+MCP_URL_ENV_NAME = "WEBZ_MCP_URL"
+PREFERRED_TOOL_NAME = "news_search_by_webz"
+MCP_TRANSPORT = "streamable-http"
+
+
+class WebzConfigError(ValueError):
+    """Raised when the Webz MCP client cannot be configured or loaded."""
+
+
+def resolve_api_token(api_token: str | None = None) -> str:
+    token = (api_token or os.getenv(TOKEN_ENV_NAME) or "").strip()
+    if not token:
+        raise WebzConfigError(
+            f"missing Webz API token. set {TOKEN_ENV_NAME} or pass api_token."
+        )
+    return token
+
+
+def resolve_mcp_url(mcp_url: str | None = None) -> str:
+    url = (mcp_url or os.getenv(MCP_URL_ENV_NAME) or DEFAULT_MCP_URL).strip()
+    if not url:
+        raise WebzConfigError("missing MCP url.")
+    return url.rstrip("/")
+
+
+def build_server_params(
+    api_token: str | None = None,
+    *,
+    mcp_url: str | None = None,
+) -> dict[str, Any]:
+    token = resolve_api_token(api_token)
+    url = resolve_mcp_url(mcp_url)
+    return {
+        "url": url,
+        "transport": MCP_TRANSPORT,
+        "headers": {"Authorization": f"Bearer {token}"},
+    }
+
+
+def pick_news_search_tool(tools: list[BaseTool]) -> BaseTool:
+    if not tools:
+        raise WebzConfigError("MCP server returned no tools.")
+    for tool in tools:
+        if tool.name == PREFERRED_TOOL_NAME:
+            return tool
+    if len(tools) == 1:
+        return tools[0]
+    names = ", ".join(tool.name for tool in tools)
+    raise WebzConfigError(
+        f"MCP server did not expose {PREFERRED_TOOL_NAME}. available tools: {names}"
+    )
+
+
+class WebzioNewsSearchToolSchema(BaseModel):
+    """Minimal static schema; replaced at init with the live MCP schema."""
+
+    model_config = ConfigDict(extra="allow")
+
+    query: str = Field(..., description="Natural-language news search query")
+
+
+class WebzioNewsSearchTool(BaseTool):
+    """Search global news with Webz.io via the hosted News Search MCP server.
+
+    Filter fields are loaded live from MCP ``tools/list``. New server filters appear
+    automatically at runtime without republishing crewai-tools.
+
+    Use as a context manager or call ``stop()`` when done to shut down the MCP session.
+    """
+
+    name: str = PREFERRED_TOOL_NAME
+    description: str = (
+        "Search global news with Webz.io. Returns article excerpts with titles, "
+        "URLs, and metadata. Filter by language, country, date, sentiment, domain, "
+        "ticker, and more."
+    )
+    args_schema: type[BaseModel] = WebzioNewsSearchToolSchema
+    package_dependencies: list[str] = Field(default_factory=lambda: ["mcp"])
+    env_vars: list[EnvVar] = Field(
+        default_factory=lambda: [
+            EnvVar(
+                name=TOKEN_ENV_NAME,
+                description="Webz.io API token from the dashboard",
+                required=True,
+            ),
+            EnvVar(
+                name=MCP_URL_ENV_NAME,
+                description="Override MCP endpoint for testing",
+                required=False,
+            ),
+        ]
+    )
+
+    _adapter: MCPServerAdapter | None = PrivateAttr(default=None)
+    _live_tool: BaseTool | None = PrivateAttr(default=None)
+
+    def __init__(
+        self,
+        api_token: str | None = None,
+        *,
+        mcp_url: str | None = None,
+        connect_timeout: int = 30,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._adapter = MCPServerAdapter(
+            build_server_params(api_token, mcp_url=mcp_url),
+            PREFERRED_TOOL_NAME,
+            connect_timeout=connect_timeout,
+        )
+        self._live_tool = pick_news_search_tool(list(self._adapter.tools))
+        self.args_schema = self._live_tool.args_schema
+        self.description = self._live_tool.description
+
+    @property
+    def arg_names(self) -> list[str]:
+        """Live argument names from the MCP tool schema."""
+        return list(self.args_schema.model_fields.keys())
+
+    def _run(self, **kwargs: Any) -> str:
+        if self._live_tool is None:
+            raise WebzConfigError("MCP news search tool is not initialized.")
+        result = self._live_tool._run(**kwargs)
+        return str(result)
+
+    def stop(self) -> None:
+        """Stop the underlying MCP server connection."""
+        if self._adapter is not None:
+            self._adapter.stop()
+            self._adapter = None
+            self._live_tool = None
+
+    def __enter__(self) -> WebzioNewsSearchTool:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.stop()

crewai_webzio-0.1.0/upstream/lib/crewai-tools/tests/tools/webzio_news_search_tool_test.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from crewai_tools.tools.webzio_tools.webzio_news_search_tool import (
+    PREFERRED_TOOL_NAME,
+    TOKEN_ENV_NAME,
+    WebzConfigError,
+    WebzioNewsSearchTool,
+    build_server_params,
+    pick_news_search_tool,
+    resolve_api_token,
+    resolve_mcp_url,
+)
+
+
+class LiveArgsSchema(BaseModel):
+    query: str = Field(..., description="Search query")
+    k: int = Field(default=10, description="Number of results")
+    extra_filter: str = Field(default="x", description="From MCP server")
+
+
+class FakeLiveTool(BaseTool):
+    name: str = PREFERRED_TOOL_NAME
+    description: str = "Live MCP news search tool"
+    args_schema: type[BaseModel] = LiveArgsSchema
+
+    def _run(self, **kwargs: object) -> str:
+        return f"result:{kwargs.get('query')}"
+
+
+class FakeMcpAdapter:
+    def __init__(
+        self,
+        serverparams: dict,
+        *tool_names: str,
+        connect_timeout: int = 30,
+    ) -> None:
+        self.serverparams = serverparams
+        self.tool_names = tool_names
+        self.connect_timeout = connect_timeout
+        self._stopped = False
+        self.tools = [FakeLiveTool()]
+
+    def stop(self) -> None:
+        self._stopped = True
+
+
+def test_resolve_api_token_requires_value(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv(TOKEN_ENV_NAME, raising=False)
+    with pytest.raises(WebzConfigError, match="missing Webz API token"):
+        resolve_api_token()
+
+
+@patch(
+    "crewai_tools.tools.webzio_tools.webzio_news_search_tool.MCPServerAdapter",
+    FakeMcpAdapter,
+)
+def test_webzio_news_search_tool_loads_live_schema_and_delegates_run() -> None:
+    tool = WebzioNewsSearchTool(api_token="tok", mcp_url="https://example.test/mcp")
+    try:
+        assert tool.name == PREFERRED_TOOL_NAME
+        assert "query" in tool.arg_names
+        assert "extra_filter" in tool.arg_names
+        assert tool._run(query="EU AI", k=3) == "result:EU AI"
+    finally:
+        tool.stop()
+
+
+@patch(
+    "crewai_tools.tools.webzio_tools.webzio_news_search_tool.MCPServerAdapter",
+    FakeMcpAdapter,
+)
+def test_webzio_news_search_tool_context_manager_stops_adapter() -> None:
+    with WebzioNewsSearchTool(api_token="tok") as tool:
+        assert tool._adapter is not None
+        adapter = tool._adapter
+    assert adapter._stopped is True
+
+
+def test_pick_news_search_tool_prefers_named_tool() -> None:
+    preferred = SimpleNamespace(name=PREFERRED_TOOL_NAME)
+    other = SimpleNamespace(name="other_tool")
+    assert pick_news_search_tool([other, preferred]) is preferred  # type: ignore[arg-type]
+
+
+def test_build_server_params_uses_bearer_header() -> None:
+    params = build_server_params("secret-token", mcp_url="https://example.test/mcp")
+    assert params["headers"]["Authorization"] == "Bearer secret-token"
+    assert params["transport"] == "streamable-http"
+
+
+def test_deprecated_alias_excluded_from_tool_specs() -> None:
+    from crewai_tools.generate_tool_specs import ToolSpecExtractor
+
+    names = {tool["name"] for tool in ToolSpecExtractor().extract_all_tools()}
+    assert "WebzioNewsSearchTool" in names