strands-you 0.1.0__tar.gz

strands_you-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+dist/
+src/strands_you/mcp.json
+src/strands_you/skills/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/

strands_you-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

strands_you-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: strands-you
+Version: 0.1.0
+Summary: You.com MCP servers and skills for Strands Agents
+Project-URL: Homepage, https://github.com/youdotcom-oss/agent-skills/tree/main/packages/strands-agents/python
+Project-URL: Documentation, https://github.com/youdotcom-oss/agent-skills#readme
+Project-URL: Repository, https://github.com/youdotcom-oss/agent-skills
+Project-URL: Issues, https://github.com/youdotcom-oss/agent-skills/issues
+Author-email: "You.com" <oss@you.com>
+License: MIT
+Keywords: agents,ai,strands,tool
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: strands-agents>=1.0.0
+Description-Content-Type: text/markdown
+
+# strands-you
+
+You.com MCP servers and Agent Skills for [Strands Agents](https://strandsagents.com), in one Python plugin.
+
+`YouDotComPlugin` registers the You.com MCP servers (search, content extraction, cited research, finance data, docs lookup) and the bundled You.com Agent Skills, so a Strands agent gets web-grounded tools and the skills to use them well in one line.
+
+## Install
+
+```sh
+pip install strands-you
+```
+
+## Quickstart
+
+```python
+from strands import Agent
+from strands_you import YouDotComPlugin
+
+agent = Agent(plugins=[YouDotComPlugin()])
+result = agent("What changed in the latest release of strands-agents? Cite sources.")
+```
+
+The API key comes from `YDC_API_KEY` by default, or pass it explicitly: `YouDotComPlugin(api_key="...")`. Get one at [you.com/platform](https://you.com/platform).
+
+## What it configures
+
+- MCP servers from `mcp.json`: `you`, `you-finance`, `you-research` (auth via
+  `YDC_API_KEY`), plus keyless `you-discover` and `you-docs`
+- Skills from the bundled `skills/`: `you-web`, `you-research`, `you-finance`,
+  `you-discover`
+
+Without an API key the keyed servers are skipped with a warning and the agent is told which servers are unavailable; keyless servers always work. The shipped server and skill sets mirror the repo-root `skills/` and `mcp.json` at release time.
+
+## Build and test
+
+```sh
+bun scripts/stage.ts   # stage shared skills + mcp.json (gitignored)
+uv sync --group dev
+uv run pytest -q
+```
+
+The Python package shares its version line with the TypeScript package (`packages/strands-agents/typescript`); both are stamped by the release plan's `strands` unit.
+
+## License
+
+MIT. Bundled skills are from this repository, MIT.

strands_you-0.1.0/README.md

@@ -0,0 +1,46 @@
+# strands-you
+
+You.com MCP servers and Agent Skills for [Strands Agents](https://strandsagents.com), in one Python plugin.
+
+`YouDotComPlugin` registers the You.com MCP servers (search, content extraction, cited research, finance data, docs lookup) and the bundled You.com Agent Skills, so a Strands agent gets web-grounded tools and the skills to use them well in one line.
+
+## Install
+
+```sh
+pip install strands-you
+```
+
+## Quickstart
+
+```python
+from strands import Agent
+from strands_you import YouDotComPlugin
+
+agent = Agent(plugins=[YouDotComPlugin()])
+result = agent("What changed in the latest release of strands-agents? Cite sources.")
+```
+
+The API key comes from `YDC_API_KEY` by default, or pass it explicitly: `YouDotComPlugin(api_key="...")`. Get one at [you.com/platform](https://you.com/platform).
+
+## What it configures
+
+- MCP servers from `mcp.json`: `you`, `you-finance`, `you-research` (auth via
+  `YDC_API_KEY`), plus keyless `you-discover` and `you-docs`
+- Skills from the bundled `skills/`: `you-web`, `you-research`, `you-finance`,
+  `you-discover`
+
+Without an API key the keyed servers are skipped with a warning and the agent is told which servers are unavailable; keyless servers always work. The shipped server and skill sets mirror the repo-root `skills/` and `mcp.json` at release time.
+
+## Build and test
+
+```sh
+bun scripts/stage.ts   # stage shared skills + mcp.json (gitignored)
+uv sync --group dev
+uv run pytest -q
+```
+
+The Python package shares its version line with the TypeScript package (`packages/strands-agents/typescript`); both are stamped by the release plan's `strands` unit.
+
+## License
+
+MIT. Bundled skills are from this repository, MIT.

strands_you-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strands-you"
+version = "0.1.0"
+description = "You.com MCP servers and skills for Strands Agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "You.com", email = "oss@you.com"}
+]
+keywords = ["strands", "agents", "ai", "tool"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "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",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "strands-agents>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/youdotcom-oss/agent-skills/tree/main/packages/strands-agents/python"
+Documentation = "https://github.com/youdotcom-oss/agent-skills#readme"
+Repository = "https://github.com/youdotcom-oss/agent-skills"
+Issues = "https://github.com/youdotcom-oss/agent-skills/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0,<9.0.0",
+    "pytest-asyncio>=0.25.0,<1.0.0",
+    "ruff>=0.11.0,<1.0.0",
+    "mypy>=1.15.0,<2.0.0",
+]
+
+# Environment management is uv: `uv sync` creates .venv from uv.lock, and
+# everything runs through `uv run` (see CI). Hatchling remains the build
+# backend — `uv build` drives it for release artifacts.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strands_you"]
+
+[tool.ruff]
+line-length = 120
+include = ["src/**/*.py", "tests/**/*.py"]
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"

strands_you-0.1.0/scripts/stage.ts

@@ -0,0 +1,35 @@
+/**
+ * Stage the shared You.com assets from the repo root into the Python package
+ * (gitignored build inputs): repo-root skills/ + mcp.json ->
+ * src/strands_you/{skills/,mcp.json}. Run before `uv build` and
+ * before tests — the plugin loads the shipped assets via importlib.resources,
+ * so tests exercise exactly what the wheel will contain.
+ *
+ * MINIMAL: staging logic duplicated per package instead of a shared root
+ * helper — the house pattern is self-contained package builds. Upgrade path:
+ * extract a shared scripts/copy-skills.ts when a sixth consumer appears.
+ */
+import { cpSync, readdirSync, rmSync, statSync } from 'node:fs'
+
+const repoRoot = new URL('../../../../', import.meta.url)
+const packageAssetsDir = new URL('../src/strands_you/', import.meta.url)
+
+const isDirectory = (path: URL) => statSync(path, { throwIfNoEntry: false })?.isDirectory()
+
+if (!isDirectory(new URL('skills/', repoRoot))) throw new Error(`Missing source skills directory: ${repoRoot}skills/`)
+
+rmSync(new URL('skills/', packageAssetsDir), { recursive: true, force: true })
+rmSync(new URL('mcp.json', packageAssetsDir), { force: true })
+
+let staged = 0
+for (const entry of readdirSync(new URL('skills/', repoRoot))) {
+  const sourceSkillDir = new URL(`skills/${entry}/`, repoRoot)
+  if (isDirectory(sourceSkillDir) && statSync(new URL('SKILL.md', sourceSkillDir), { throwIfNoEntry: false })) {
+    cpSync(sourceSkillDir, new URL(`skills/${entry}/`, packageAssetsDir), { recursive: true })
+    staged += 1
+  }
+}
+if (staged === 0) throw new Error(`No skills found in ${repoRoot}skills/`)
+cpSync(new URL('mcp.json', repoRoot), new URL('mcp.json', packageAssetsDir), { force: true })
+
+console.log(`staged ${staged} skills + mcp.json -> src/strands_you/`)

strands_you-0.1.0/src/strands_you/__init__.py

@@ -0,0 +1,7 @@
+"""Strands Package."""
+
+from strands_you.plugin import YouDotComPlugin
+
+__all__ = [
+    "YouDotComPlugin",
+]

strands_you-0.1.0/src/strands_you/plugin.py

@@ -0,0 +1,117 @@
+"""You.com plugin for Strands Agents.
+
+Bundles the You.com MCP servers (from the shipped ``mcp.json``) and the You.com
+Agent Skills (from the bundled ``skills/`` directory) into a single plugin:
+
+    ```python
+    from strands import Agent
+    from strands_you import YouDotComPlugin
+
+    agent = Agent(plugins=[YouDotComPlugin()])
+    ```
+
+Servers that require an API key are enabled only when ``YDC_API_KEY`` (or the
+explicit ``api_key`` argument) is available; keyless servers are always enabled.
+"""
+
+import json
+import logging
+import os
+import warnings
+from importlib import resources
+from typing import Any
+
+from strands.hooks import BeforeInvocationEvent
+from strands.plugins import hook
+from strands.tools.mcp import MCPClient
+from strands.vended_plugins.skills import AgentSkills
+
+logger = logging.getLogger(__name__)
+
+#: Servers that authenticate with ``YDC_API_KEY``. Any server in the shipped
+#: ``mcp.json`` not listed here is treated as keyless. Keying this policy by
+#: server name keeps the shipped ``mcp.json`` the single source of truth for
+#: server topology (urls) while auth policy stays a consumer-side concern.
+_API_KEY_SERVERS = frozenset({"you", "you-finance", "you-research"})
+
+_API_KEY_ENV_VAR = "YDC_API_KEY"
+
+_CAPABILITY_NOTE_MARKER = "unavailable You.com MCP servers"
+
+
+def _load_mcp_config() -> dict[str, dict[str, Any]]:
+    """Load the shipped ``mcp.json`` and return its server entries by name."""
+    mcp_config: Any = json.loads(resources.files("strands_you").joinpath("mcp.json").read_text(encoding="utf-8"))
+    servers: dict[str, dict[str, Any]] = mcp_config.get("mcpServers", {})
+    return servers
+
+
+class YouDotComPlugin(AgentSkills):
+    """Strands plugin bundling You.com MCP servers and Agent Skills.
+
+    Subclasses the SDK's ``AgentSkills`` plugin so the bundled skills are
+    discovered and activated by the agent, and registers one MCP client per
+    enabled server when attached to an agent.
+
+    Args:
+        api_key: You.com API key. Defaults to the ``YDC_API_KEY`` environment
+            variable. When absent, servers that require a key are skipped with
+            a warning and only keyless servers are enabled.
+    """
+
+    name = "youdotcom"
+
+    def __init__(self, api_key: str | None = None) -> None:
+        """Initialize the plugin from the shipped ``mcp.json``."""
+        self._api_key = api_key if api_key is not None else os.environ.get(_API_KEY_ENV_VAR)
+        self._all_servers = _load_mcp_config()
+        self._servers = {name: server for name, server in self._all_servers.items() if self._server_enabled(name)}
+        self._skipped_servers = sorted(set(self._all_servers) - set(self._servers))
+        super().__init__(skills=[str(resources.files("strands_you").joinpath("skills"))])
+
+    def _server_enabled(self, name: str) -> bool:
+        """Return True when the named server is usable with the current auth."""
+        if name not in _API_KEY_SERVERS:
+            return True
+        if self._api_key:
+            return True
+        warnings.warn(
+            f"Server {name!r} requires an API key; set YDC_API_KEY to enable it. Enabled keyless servers only.",
+            stacklevel=2,
+        )
+        return False
+
+    @property
+    def servers(self) -> dict[str, dict[str, Any]]:
+        """Enabled MCP server configs by name, as shipped in ``mcp.json``."""
+        return dict(self._servers)
+
+    def init_agent(self, agent: Any) -> None:  # type: ignore[override]  # registry supports sync init
+        """Register one MCP client per enabled server with the agent.
+
+        Args:
+            agent: The agent instance the plugin is attached to.
+        """
+        for name, server in self._servers.items():
+            headers = {"Authorization": f"Bearer {self._api_key}"} if name in _API_KEY_SERVERS else None
+            client = MCPClient(url=server["url"], headers=headers)
+            agent.tool_registry.process_tools([client])
+            logger.debug("server=<%s> | registered MCP client", name)
+
+    @hook  # type: ignore[call-overload]  # same as the SDK's own plugin template
+    async def _on_before_invocation_note(self, event: BeforeInvocationEvent) -> None:
+        """Tell the agent which servers are unavailable when no API key is set.
+
+        Without this, an agent running keyless discovers its own capability
+        boundary only by failing tool calls. Runs on every invocation; the note
+        is appended once (idempotent via a stable marker).
+        """
+        if self._api_key or not self._skipped_servers:
+            return
+        note = (
+            f"The following You.com MCP servers are {_CAPABILITY_NOTE_MARKER} "
+            f"because no API key is configured: {', '.join(self._skipped_servers)}. "
+            f"Set {_API_KEY_ENV_VAR} to enable them."
+        )
+        if hasattr(event.agent, "system_prompt") and _CAPABILITY_NOTE_MARKER not in (event.agent.system_prompt or ""):
+            event.agent.system_prompt = (event.agent.system_prompt or "") + "\n\n" + note

strands_you-0.1.0/tests/test_plugin.py

@@ -0,0 +1,137 @@
+"""Tests for YouDotComPlugin."""
+
+import asyncio
+
+import pytest
+from strands import Agent
+from strands.hooks import BeforeInvocationEvent
+
+import strands_you.plugin as plugin_mod
+from strands_you import YouDotComPlugin
+
+#: The server set comes from the shipped mcp.json mirror, which the release
+#: sync owns. Expectations are derived from it so a sync that adds or removes
+#: a server never breaks these tests — the auth policy, not the topology, is
+#: what they pin down.
+ALL_SERVERS = set(plugin_mod._load_mcp_config())
+KEYED_SERVERS = set(plugin_mod._API_KEY_SERVERS)
+KEYLESS_SERVERS = ALL_SERVERS - KEYED_SERVERS
+
+
+class _InertProvider:
+    """Stands in for a real MCPClient so tests never touch the network."""
+
+    async def load_tools(self, **kwargs):
+        return []
+
+    def add_consumer(self, registry_id):
+        pass
+
+
+def test_plugin_exposes_stable_name():
+    """The plugin exposes its stable name."""
+    plugin = YouDotComPlugin()
+    assert plugin.name == "youdotcom"
+
+
+def test_without_api_key_only_keyless_servers_are_enabled(monkeypatch: pytest.MonkeyPatch):
+    """Without YDC_API_KEY, keyed servers are skipped and keyless ones remain."""
+    monkeypatch.delenv("YDC_API_KEY", raising=False)
+    plugin = YouDotComPlugin()
+    assert set(plugin.servers) == KEYLESS_SERVERS
+
+
+def test_with_api_key_all_servers_are_enabled(monkeypatch: pytest.MonkeyPatch):
+    """With YDC_API_KEY (env or explicit), every shipped server is enabled."""
+    monkeypatch.setenv("YDC_API_KEY", "test-key")
+    from_env = YouDotComPlugin()
+    explicit = YouDotComPlugin(api_key="explicit-key")
+    assert set(from_env.servers) == ALL_SERVERS
+    assert set(explicit.servers) == ALL_SERVERS
+
+
+class _FakeAgent:
+    """Captures tool providers the way the plugin registry would register them."""
+
+    def __init__(self) -> None:
+        self.providers: list[object] = []
+
+        class _Registry:
+            def __init__(self, outer: "_FakeAgent") -> None:
+                self._outer = outer
+
+            def process_tools(self, tools: list[object]) -> list[str]:
+                self._outer.providers.extend(tools)
+                return []
+
+        self.tool_registry = _Registry(self)
+
+
+def test_init_agent_registers_one_client_per_enabled_server(monkeypatch: pytest.MonkeyPatch):
+    """init_agent hands one MCP client per enabled server to the tool registry,
+    with a Bearer header on keyed servers and no header on keyless ones."""
+    client_calls: list[dict] = []
+
+    def fake_mcp_client(_factory=None, *, url=None, headers=None, **_kwargs):
+        client_calls.append({"url": url, "headers": headers})
+        return object()
+
+    monkeypatch.setattr(plugin_mod, "MCPClient", fake_mcp_client)
+
+    plugin = YouDotComPlugin(api_key="test-key")
+    fake_agent = _FakeAgent()
+    plugin.init_agent(fake_agent)  # type: ignore[arg-type]
+
+    assert len(fake_agent.providers) == len(ALL_SERVERS)
+    by_url = {call["url"]: call["headers"] for call in client_calls}
+    assert len(client_calls) == len(ALL_SERVERS)
+    for name, server in plugin.servers.items():
+        if name in KEYED_SERVERS:
+            assert by_url[server["url"]] == {"Authorization": "Bearer test-key"}
+        else:
+            assert by_url[server["url"]] is None
+
+
+def test_attached_agent_discovers_bundled_skills_and_skills_tool(monkeypatch: pytest.MonkeyPatch):
+    """An agent with the plugin gains the skills tool and sees the bundled skills."""
+    monkeypatch.setattr(plugin_mod, "MCPClient", lambda *args, **kwargs: _InertProvider())
+
+    agent = Agent(plugins=[YouDotComPlugin()])
+
+    assert "skills" in agent.tool_registry.get_all_tools_config()
+    attached = agent._plugin_registry._plugins["youdotcom"]
+    # Skill discovery is lazy: the same load runs at each invocation via the
+    # BeforeInvocationEvent hook. Exercise that exact path here.
+    asyncio.run(attached._on_before_invocation(BeforeInvocationEvent(agent=agent)))
+    names = {skill.name for skill in attached.get_available_skills(agent)}
+    assert names == {"you-web", "you-research", "you-discover", "you-finance"}
+
+
+def test_without_key_agent_system_prompt_notes_skipped_servers(monkeypatch: pytest.MonkeyPatch):
+    """Without a key the agent's system prompt says which servers are unavailable."""
+    monkeypatch.delenv("YDC_API_KEY", raising=False)
+    monkeypatch.setattr(plugin_mod, "MCPClient", lambda *args, **kwargs: _InertProvider())
+
+    agent = Agent(plugins=[YouDotComPlugin()])
+    attached = agent._plugin_registry._plugins["youdotcom"]
+    # The registry runs every callback registered for the event; replicate that
+    # ordering here: the inherited skills hook, then the capability-note hook.
+    asyncio.run(attached._on_before_invocation(BeforeInvocationEvent(agent=agent)))
+    asyncio.run(attached._on_before_invocation_note(BeforeInvocationEvent(agent=agent)))
+
+    assert "YDC_API_KEY" in agent.system_prompt
+    for name in KEYED_SERVERS:  # servers the agent can NOT call
+        assert name in agent.system_prompt
+
+
+def test_with_key_agent_system_prompt_has_no_capability_note(monkeypatch: pytest.MonkeyPatch):
+    """With a key present, no capability note is injected."""
+    monkeypatch.setenv("YDC_API_KEY", "test-key")
+    monkeypatch.setattr(plugin_mod, "MCPClient", lambda *args, **kwargs: _InertProvider())
+
+    agent = Agent(plugins=[YouDotComPlugin()])
+    attached = agent._plugin_registry._plugins["youdotcom"]
+    asyncio.run(attached._on_before_invocation(BeforeInvocationEvent(agent=agent)))
+    asyncio.run(attached._on_before_invocation_note(BeforeInvocationEvent(agent=agent)))
+
+    assert "YDC_API_KEY" not in agent.system_prompt