agentshim 0.9.0__tar.gz → 0.10.0__tar.gz

{agentshim-0.9.0 → agentshim-0.10.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.10.0 (2026-10-03)
+
+MCP isolation. Additive: the default scope keeps today's behaviour. Adds a
+runtime dependency on `tomli` for Python 3.10 only (Codex config parsing).
+
+### Added
+
+- `McpScope` (`ALL`, `SESSION`) and `start_session(mcp_scope=...)` /
+  `run(mcp_scope=...)`. `SESSION` connects the CLI only to the servers in
+  `TurnRequest.mcp_servers`; a turn given none sees no MCP server. It is a
+  separate option from `SkillScope` because a provider may enforce one and not
+  the other; each is refused independently.
+- `ProviderProfile.mcp_scopes` declares the scopes a provider enforces;
+  asking for another raises `ProviderCapabilityError` from `start_session`.
+- `ArgvContext.mcp_scope` and `ArgvContext.mcp_servers` carry the scope and
+  the turn's servers to `build_argv`.
+- Claude Code: `SESSION` passes `--strict-mcp-config` plus the turn's servers
+  inline as `--mcp-config`. This drops user and project (`.mcp.json`) servers,
+  plugin servers and claude.ai account connectors.
+- Codex: `SESSION` sets `enabled = false` on every `mcp_servers` entry found
+  in `$CODEX_HOME/config.toml`, `/etc/codex/config.toml` and
+  `<cwd>/.codex/config.toml` that the turn was not given, and sets
+  `features.plugins=false` and `features.apps=false` (plugin servers and the
+  account's ChatGPT apps).
+- Gemini, opencode and Copilot support `ALL` only.
+- Live e2e: a server seeded into the CLI's default configuration is reachable
+  under `ALL` and not under `SESSION` (`tests/e2e/test_mcp_scope_e2e.py`).
+
+### Changed
+
+- `parse_mcp_servers` ignores `enabled=false` overrides: they disable a
+  configured server and do not define one.
+
 ## 0.9.0 (2026-10-03)
 
 Skill isolation. Additive: the default scope keeps today's behaviour.

{agentshim-0.9.0 → agentshim-0.10.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.9.0
+Version: 0.10.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
+Requires-Dist: tomli>=2; python_full_version < '3.11'
 Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == 'test'
 Description-Content-Type: text/markdown

{agentshim-0.9.0 → agentshim-0.10.0}/agentshim/__init__.py

@@ -27,6 +27,7 @@ from .core import (
     McpConfigError,
     McpInstallation,
     McpMechanism,
+    McpScope,
     McpServer,
     McpTransport,
     ModelPricing,
@@ -97,7 +98,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 
 __all__ = [
     "AgentEvent",
@@ -134,6 +135,7 @@ __all__ = [
     "McpConfigError",
     "McpInstallation",
     "McpMechanism",
+    "McpScope",
     "McpServer",
     "McpTransport",
     "ModelPricing",

{agentshim-0.9.0 → agentshim-0.10.0}/agentshim/agent.py

@@ -23,7 +23,13 @@ from agentshim.core.errors import (
     SessionResumeError,
 )
 from agentshim.core.events import RunFinished, RunStarted, compose_event_handlers
-from agentshim.core.profile import McpMechanism, OutputSchemaStyle, SchemaDialect, SkillScope
+from agentshim.core.profile import (
+    McpMechanism,
+    McpScope,
+    OutputSchemaStyle,
+    SchemaDialect,
+    SkillScope,
+)
 from agentshim.core.provider import ArgvContext
 from agentshim.core.schema import compact_json, dialect_problems, materialize
 from agentshim.core.skills import SkillTracker
@@ -115,13 +121,20 @@ class CliAgent:
         timeout: float | None = None,
         session_id: str | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
+        mcp_scope: McpScope = McpScope.ALL,
     ) -> AgentSession:
         """Open a conversation whose turns resume one another.
 
-        ``skill_scope`` is fixed for the conversation (see ``AgentSession``).
+        ``skill_scope`` and ``mcp_scope`` are fixed for the conversation (see
+        ``AgentSession``).
         """
         return AgentSession(
-            self, cwd=cwd, timeout=timeout, session_id=session_id, skill_scope=skill_scope
+            self,
+            cwd=cwd,
+            timeout=timeout,
+            session_id=session_id,
+            skill_scope=skill_scope,
+            mcp_scope=mcp_scope,
         )
 
     def run(
@@ -131,9 +144,12 @@ class CliAgent:
         cwd: str | None = None,
         timeout: float | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
+        mcp_scope: McpScope = McpScope.ALL,
     ) -> TurnResult:
         """Run one turn in a throwaway session."""
-        session = self.start_session(cwd=cwd, timeout=timeout, skill_scope=skill_scope)
+        session = self.start_session(
+            cwd=cwd, timeout=timeout, skill_scope=skill_scope, mcp_scope=mcp_scope
+        )
         return session.turn(request)
 
 
@@ -144,7 +160,7 @@ def _discard(message: str) -> None:
 class AgentSession:
     """A provider conversation. One turn at a time; ``cancel`` is thread-safe."""
 
-    def __init__(
+    def __init__(  # noqa: PLR0913 - one keyword per independent session option
         self,
         agent: CliAgent,
         *,
@@ -152,6 +168,7 @@ class AgentSession:
         timeout: float | None = None,
         session_id: str | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
+        mcp_scope: McpScope = McpScope.ALL,
     ) -> None:
         """Bind a conversation to one agent, with per-turn defaults.
 
@@ -162,12 +179,19 @@ class AgentSession:
         first turn resumes rather than starts fresh. ``skill_scope`` limits
         which skills every turn's CLI may discover; a scope the provider's
         ``profile.skill_scopes`` does not list raises
-        ``ProviderCapabilityError`` here, before any turn runs.
+        ``ProviderCapabilityError`` here, before any turn runs. ``mcp_scope``
+        limits which MCP servers every turn's CLI may connect to
+        (``McpScope.SESSION``: only those in ``TurnRequest.mcp_servers``) and
+        is checked against ``profile.mcp_scopes`` the same way.
         """
         if skill_scope not in agent.profile.skill_scopes:
             msg = f"{agent.profile.name} cannot limit skills to scope {skill_scope.value!r}"
             raise ProviderCapabilityError(msg)
+        if mcp_scope not in agent.profile.mcp_scopes:
+            msg = f"{agent.profile.name} cannot limit MCP servers to scope {mcp_scope.value!r}"
+            raise ProviderCapabilityError(msg)
         self.skill_scope = skill_scope
+        self.mcp_scope = mcp_scope
         self._agent = agent
         self._cwd = cwd
         self._timeout = timeout
@@ -277,6 +301,8 @@ class AgentSession:
                     extra_args=req.extra_args,
                     cwd=cwd,
                     skill_scope=self.skill_scope,
+                    mcp_scope=self.mcp_scope,
+                    mcp_servers=tuple(req.mcp_servers),
                 )
             )
             command = CommandRequest(argv=argv, stdin=req.prompt, cwd=cwd, env=env, timeout=timeout)

{agentshim-0.9.0 → agentshim-0.10.0}/agentshim/core/__init__.py

@@ -55,6 +55,7 @@ from .mcp import (
 from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .profile import (
     McpMechanism,
+    McpScope,
     OutputSchemaStyle,
     ProviderProfile,
     SchemaDialect,
@@ -88,6 +89,7 @@ __all__ = [
     "McpConfigError",
     "McpInstallation",
     "McpMechanism",
+    "McpScope",
     "McpServer",
     "McpTransport",
     "ModelPricing",

{agentshim-0.9.0 → agentshim-0.10.0}/agentshim/core/profile.py

@@ -77,6 +77,22 @@ class SkillScope(Enum):
     PROJECT = "project"
 
 
+class McpScope(Enum):
+    """Which MCP servers a session's CLI may connect to.
+
+    ``ALL``: whatever the CLI finds by default, including the user's and the
+    project's own MCP configuration, plugin servers and account-level
+    connectors. ``SESSION``: only the servers the session was given through
+    ``TurnRequest.mcp_servers``; a session given none sees no MCP server at
+    all. A provider declares the scopes it can enforce in
+    ``ProviderProfile.mcp_scopes``; asking for another one is an error, never
+    a silent ``ALL``.
+    """
+
+    ALL = "all"
+    SESSION = "session"
+
+
 def _no_container_env() -> Mapping[str, str]:
     """Empty read-only default: a frozen spec must not carry a mutable one.
 
@@ -127,3 +143,5 @@ class ProviderProfile:
     skill_invocation: SkillSignal = SkillSignal.NONE
     #: The ``SkillScope`` values a session on this provider may request.
     skill_scopes: frozenset[SkillScope] = frozenset({SkillScope.ALL})
+    #: The ``McpScope`` values a session on this provider may request.
+    mcp_scopes: frozenset[McpScope] = frozenset({McpScope.ALL})

{agentshim-0.9.0 → agentshim-0.10.0}/agentshim/core/provider.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol
 
-from .profile import SkillScope
+from .profile import McpScope, SkillScope
 from .usage import ProviderUsage
 
 if TYPE_CHECKING:
@@ -41,6 +41,13 @@ class ArgvContext:
     #: Which skills the CLI may discover; the session has already checked
     #: that the provider's profile supports it.
     skill_scope: SkillScope = SkillScope.ALL
+    #: Which MCP servers the CLI may connect to; the session has already
+    #: checked that the provider's profile supports it.
+    mcp_scope: McpScope = McpScope.ALL
+    #: The servers the turn was given (the ones ``install_mcp`` installed).
+    #: A provider enforcing ``McpScope.SESSION`` renders them itself when its
+    #: installed config file is not enough to exclude the user's own.
+    mcp_servers: Sequence[McpServer] = ()
 
 
 @dataclass(frozen=True)

{agentshim-0.9.0 → agentshim-0.10.0}/agentshim/providers/claude/provider.py

@@ -9,6 +9,7 @@ from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import HttpMcpServer, NoopInstallation, StdioMcpServer, install_config_file
 from agentshim.core.profile import (
     McpMechanism,
+    McpScope,
     OutputSchemaStyle,
     ProviderProfile,
     SchemaDialect,
@@ -43,6 +44,12 @@ MCP_SERVER_KEY = "mcpServers"
 #: account connectors are not user settings and stay.
 PROJECT_SETTING_SOURCES = ("--setting-sources", "project,local")
 
+#: ``McpScope.SESSION``: ``--strict-mcp-config`` makes ``--mcp-config`` the
+#: only source of MCP servers. It drops the user's and the project's
+#: (``.mcp.json``) servers, plugin servers and claude.ai account connectors,
+#: so the servers the turn was given are passed inline as ``--mcp-config``.
+STRICT_MCP_FLAG = "--strict-mcp-config"
+
 PROFILE = ProviderProfile(
     name="claude",
     display_name="Claude Code",
@@ -67,6 +74,7 @@ PROFILE = ProviderProfile(
     skill_discovery=SkillSignal.STRUCTURED,
     skill_invocation=SkillSignal.STRUCTURED,
     skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
+    mcp_scopes=frozenset({McpScope.ALL, McpScope.SESSION}),
     container_install=(
         "apt-get update && apt-get install -y --no-install-recommends curl ca-certificates",
         "curl -fsSL https://claude.ai/install.sh | bash",
@@ -141,6 +149,8 @@ class ClaudeProvider:
         settings = build_settings(self.sandbox, hooks=self.hooks)
         if settings:
             argv += ["--settings", json.dumps(settings)]
+        if ctx.mcp_scope is McpScope.SESSION:
+            argv += _session_mcp_argv(ctx.mcp_servers)
         argv += list(ctx.mcp_argv)
         argv += list(ctx.extra_args)
         return argv
@@ -193,6 +203,15 @@ def _resumed_session_id(argv: Sequence[str]) -> str | None:
     return args[index + 1]
 
 
+def _session_mcp_argv(servers: Sequence[McpServer]) -> list[str]:
+    """Flags that leave Claude Code exactly *servers* and nothing else."""
+    argv = [STRICT_MCP_FLAG]
+    if servers:
+        config = {MCP_SERVER_KEY: {server.name: mcp_entry(server) for server in servers}}
+        argv += ["--mcp-config", json.dumps(config)]
+    return argv
+
+
 def mcp_entry(server: McpServer) -> dict[str, Any]:
     """Render one server the way ``.mcp.json`` describes it."""
     if server.startup_timeout_s is not None:

agentshim-0.10.0/agentshim/providers/codex/mcp_scope.py

@@ -0,0 +1,93 @@
+"""Codex MCP servers: hide every one the session was not given.
+
+Codex merges MCP servers from several layers: ``$CODEX_HOME/config.toml``,
+system config, a trusted workspace's ``.codex/config.toml``, installed
+plugins, and the account's ChatGPT apps (the ``codex_apps`` server). A
+``--config mcp_servers={}`` override does not replace the merged table, so
+each configured server is switched off by name (``enabled = false``), and
+plugins and apps are switched off as features.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING, Any, cast
+
+from ._toml import toml_str
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised on the 3.10 CI leg
+    import tomli as tomllib  # pyright: ignore[reportMissingImports]
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Iterable, Mapping
+
+_SYSTEM_CONFIG = "/etc/codex/config.toml"
+_BARE_KEY = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-")
+
+#: Features that bring in MCP servers on their own: plugins (each may bundle
+#: servers) and apps (the account's ChatGPT connectors).
+_MCP_FEATURES = ("plugins", "apps")
+
+
+def configured_server_keys(env: Mapping[str, str], cwd: str | None) -> list[str]:
+    """Every ``mcp_servers`` key the config files Codex would read define.
+
+    Reads the user's ``$CODEX_HOME/config.toml`` (default ``~/.codex``), the
+    system config, and ``<cwd>/.codex/config.toml``. A file that is missing or
+    not valid TOML contributes nothing (Codex reports a broken config itself).
+    The scan runs where agentshim runs, so a CLI in a container is only
+    covered when the container shares these files.
+    """
+    home = env.get("HOME") or os.path.expanduser("~")  # noqa: PTH111 - a str contract, not a Path
+    codex_home = env.get("CODEX_HOME") or os.path.join(home, ".codex")  # noqa: PTH118
+    paths = [os.path.join(codex_home, "config.toml"), _SYSTEM_CONFIG]  # noqa: PTH118
+    if cwd is not None:
+        paths.append(os.path.join(cwd, ".codex", "config.toml"))  # noqa: PTH118
+    keys: list[str] = []
+    for path in paths:
+        keys += _server_keys(path)
+    return list(dict.fromkeys(keys))
+
+
+def _server_keys(path: str) -> Iterable[str]:
+    config = _read_toml(path)
+    servers: object = config.get("mcp_servers")
+    if not isinstance(servers, dict):
+        return []
+    return [str(key) for key in cast("dict[object, object]", servers)]
+
+
+def _read_toml(path: str) -> dict[str, Any]:
+    try:
+        with open(path, "rb") as handle:  # noqa: PTH123 - a str contract, not a Path
+            # pyright analyzes the 3.10 leg, where the optional ``tomli`` has no
+            # stubs in the 3.12 environment: the types are known at runtime.
+            return tomllib.load(handle)  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
+    except (OSError, tomllib.TOMLDecodeError):  # pyright: ignore[reportUnknownMemberType]
+        return {}
+
+
+def _table_key(key: str) -> str:
+    return key if key and set(key) <= _BARE_KEY else toml_str(key)
+
+
+def session_scope_overrides(
+    env: Mapping[str, str], cwd: str | None, given_keys: Collection[str]
+) -> list[str]:
+    """``--config`` flags that leave Codex only the servers in *given_keys*.
+
+    *given_keys* are the ``mcp_servers`` keys the turn's own overrides define;
+    they are not disabled. A given server that shares a key with a configured
+    one is merged field by field with it by Codex, so give session servers
+    names the user's config does not use.
+    """
+    flags: list[str] = []
+    for key in configured_server_keys(env, cwd):
+        if key not in given_keys:
+            flags += ["--config", f"mcp_servers.{_table_key(key)}.enabled=false"]
+    for feature in _MCP_FEATURES:
+        flags += ["--config", f"features.{feature}=false"]
+    return flags

{agentshim-0.9.0 → agentshim-0.10.0}/agentshim/providers/codex/provider.py

@@ -10,6 +10,7 @@ from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import FlagsInstallation, HttpMcpServer, NoopInstallation
 from agentshim.core.profile import (
     McpMechanism,
+    McpScope,
     OutputSchemaStyle,
     ProviderProfile,
     SchemaDialect,
@@ -18,6 +19,7 @@ from agentshim.core.profile import (
 )
 
 from ._toml import toml_array, toml_str, unescape_toml
+from .mcp_scope import session_scope_overrides
 from .parser import CodexStreamParser
 from .rules import RULES_FILENAME
 from .sandbox import CodexSandboxConfig, resolve_sandbox, sandbox_overrides
@@ -82,6 +84,7 @@ PROFILE = ProviderProfile(
     # of a ``SKILL.md`` (``skills.py``).
     skill_invocation=SkillSignal.INFERRED,
     skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
+    mcp_scopes=frozenset({McpScope.ALL, McpScope.SESSION}),
     container_install=(_NODE_INSTALL, _CODEX_INSTALL),
     # Documented Codex CLI variable that relocates ~/.codex (``codex --help``:
     # "Layer $CODEX_HOME/<name>.config.toml on top of the base user config";
@@ -133,8 +136,7 @@ class CodexProvider:
         if ctx.model:
             argv += ["--model", ctx.model]
         argv += _shell_path_config(ctx.env)
-        if ctx.skill_scope is SkillScope.PROJECT:
-            argv += project_scope_overrides(ctx.env)
+        argv += _scope_overrides(ctx)
         if ctx.reasoning_effort:
             argv += ["--config", f"model_reasoning_effort={toml_str(ctx.reasoning_effort)}"]
         argv += list(ctx.mcp_argv)
@@ -270,6 +272,21 @@ def _shell_path_config(env: Mapping[str, str]) -> list[str]:
     return ["--config", f"shell_environment_policy.set.PATH={toml_str(path)}"]
 
 
+def _scope_overrides(ctx: ArgvContext) -> list[str]:
+    """The ``--config`` flags the session's skill and MCP scopes call for.
+
+    Both scopes switch ``features.plugins`` off; the flag is emitted once.
+    """
+    flags: list[str] = []
+    if ctx.skill_scope is SkillScope.PROJECT:
+        flags += project_scope_overrides(ctx.env)
+    if ctx.mcp_scope is McpScope.SESSION:
+        given = {server.name.replace("-", "_") for server in ctx.mcp_servers}
+        flags += session_scope_overrides(ctx.env, ctx.cwd, given)
+    pairs = [flags[i : i + 2] for i in range(0, len(flags), 2)]
+    return [item for pair in dict.fromkeys(map(tuple, pairs)) for item in pair]
+
+
 def _server_flags(server: McpServer) -> list[str]:
     """Render one MCP server as dotted-path TOML overrides.
 
@@ -338,6 +355,9 @@ def parse_mcp_servers(argv: Sequence[str]) -> dict[str, dict[str, Any]]:
     servers: dict[str, dict[str, Any]] = {}
     for key, field, raw_value in _mcp_config_overrides(argv):
         _apply_mcp_override(servers.setdefault(key, {}), field, raw_value)
+    # ``McpScope.SESSION`` also emits ``enabled=false`` overrides for servers
+    # the user configured; those define no server, so they are not reported.
+    servers = {key: entry for key, entry in servers.items() if "command" in entry or "url" in entry}
     for entry in servers.values():
         if "url" not in entry:
             entry.setdefault("args", [])

{agentshim-0.9.0 → agentshim-0.10.0}/pyproject.toml

@@ -1,10 +1,12 @@
 [project]
 name = "agentshim"
-version = "0.9.0"
+version = "0.10.0"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = []
+dependencies = [
+    "tomli>=2 ; python_full_version < '3.11'",
+]
 
 [project.optional-dependencies]
 test = [