mcp-servers-cli 0.1.0__py3-none-any.whl

mcp_servers_cli/agent.py

@@ -0,0 +1,136 @@
+"""The tool loop: the model asks, the MCP server answers, until the model replies in text.
+
+The loop prints nothing. Callers observe it through two hooks, which is how the CLI renders
+progress and how a trace can be recorded without touching the loop.
+"""
+
+import json
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from fastmcp import Client
+from mcp.shared.exceptions import MCPError
+from mcp.types import CONNECTION_CLOSED
+
+from mcp_servers_cli.llm import LLMBackend, Message, ToolCall, ToolResult, ToolSpec
+from mcp_servers_cli.rendering import to_text
+
+DEFAULT_MAX_STEPS = 10
+MAX_RESULT_CHARS = 20_000
+
+OnToolCall = Callable[[ToolCall], None]
+OnToolResult = Callable[[ToolCall, ToolResult, float], None]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentRun:
+    """How a run ended. `stopped` means the step budget ran out before a text answer."""
+
+    answer: str
+    messages: list[Message]
+    steps: int
+    stopped: bool
+
+    @property
+    def results(self) -> list[ToolResult]:
+        """Every tool result of the run, in order."""
+        return [result for message in self.messages for result in message.tool_results]
+
+    @property
+    def failed(self) -> int:
+        return sum(result.is_error for result in self.results)
+
+
+def tool_specs(tools: Sequence[Any]) -> list[ToolSpec]:
+    """MCP tools as the model sees them."""
+    return [
+        ToolSpec(
+            name=tool.name,
+            description=tool.description or "",
+            input_schema=tool.input_schema or {"type": "object", "properties": {}},
+        )
+        for tool in tools
+    ]
+
+
+def sanitize_args(args: Mapping[str, Any], schema: Mapping[str, Any]) -> dict[str, Any]:
+    """Drop arguments the schema does not declare, which models sometimes invent.
+
+    A schema without `properties`, or one that allows additional properties, is left alone.
+    """
+    properties = schema.get("properties")
+    if not properties or schema.get("additionalProperties") is True:
+        return dict(args)
+    return {key: value for key, value in args.items() if key in properties}
+
+
+def result_text(result: Any) -> str:
+    """The text a model reads back: content blocks first, structured content as a fallback."""
+    text = "\n".join(to_text(result.content))
+    if not text and result.structured_content is not None:
+        text = json.dumps(result.structured_content, ensure_ascii=False)
+    if len(text) > MAX_RESULT_CHARS:
+        text = f"{text[:MAX_RESULT_CHARS]}\n[truncated: {len(text)} characters in total]"
+    return text
+
+
+async def execute(client: Client, call: ToolCall, schemas: Mapping[str, Mapping]) -> ToolResult:
+    """Run one call. Every failure a model can recover from comes back as an error result."""
+    if call.name not in schemas:
+        available = ", ".join(sorted(schemas))
+        return ToolResult(
+            call.id, call.name, f"unknown tool '{call.name}'; available: {available}", True
+        )
+    arguments = sanitize_args(call.arguments, schemas[call.name])
+    try:
+        result = await client.call_tool(call.name, arguments, raise_on_error=False)
+    except MCPError as exc:
+        if exc.code == CONNECTION_CLOSED:
+            raise
+        return ToolResult(call.id, call.name, str(exc), True)
+    return ToolResult(call.id, call.name, result_text(result), result.is_error)
+
+
+async def first_turn(
+    client: Client, backend: LLMBackend, prompt: str, *, system: str = ""
+) -> Message:
+    """One model turn with the server's tools and nothing executed: what the model would do."""
+    specs = tool_specs(await client.list_tools())
+    return await backend.complete(system, [Message("user", prompt)], specs)
+
+
+async def run_agent(
+    client: Client,
+    backend: LLMBackend,
+    prompt: str,
+    *,
+    system: str = "",
+    max_steps: int = DEFAULT_MAX_STEPS,
+    on_tool_call: OnToolCall | None = None,
+    on_tool_result: OnToolResult | None = None,
+) -> AgentRun:
+    """Alternate model turns and tool calls until the model answers or the budget runs out."""
+    specs = tool_specs(await client.list_tools())
+    schemas = {spec.name: spec.input_schema for spec in specs}
+    messages = [Message("user", prompt)]
+
+    for step in range(1, max_steps + 1):
+        reply = await backend.complete(system, messages, specs)
+        messages.append(reply)
+        if not reply.tool_calls:
+            return AgentRun(reply.text, messages, step, stopped=False)
+
+        results = []
+        for call in reply.tool_calls:
+            if on_tool_call:
+                on_tool_call(call)
+            started = time.perf_counter()
+            result = await execute(client, call, schemas)
+            if on_tool_result:
+                on_tool_result(call, result, time.perf_counter() - started)
+            results.append(result)
+        messages.append(Message("tool", tool_results=tuple(results)))
+
+    return AgentRun("", messages, max_steps, stopped=True)

mcp_servers_cli/backends/__init__.py

@@ -0,0 +1,28 @@
+"""Backend registry. A new provider is a new module in this package plus one line here."""
+
+from importlib import import_module
+
+from mcp_servers_cli.llm import LLMBackend
+
+# Backend name -> (module, class). Each backend is named after the SDK it imports.
+BACKENDS: dict[str, tuple[str, str]] = {
+    "ollama": ("mcp_servers_cli.backends.ollama", "OllamaBackend"),
+    "anthropic": ("mcp_servers_cli.backends.anthropic", "AnthropicBackend"),
+}
+
+
+def create_backend(name: str, model: str) -> LLMBackend:
+    """Import a backend only once chosen, so an optional SDK stays optional."""
+    if name not in BACKENDS:
+        raise ValueError(f"Unknown backend '{name}'. Available: {sorted(BACKENDS)}")
+    module_name, class_name = BACKENDS[name]
+    try:
+        module = import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if exc.name != name:
+            raise
+        raise ModuleNotFoundError(
+            f"The {name} backend needs an optional dependency: install mcp-servers-cli[{name}]",
+            name=name,
+        ) from exc
+    return getattr(module, class_name)(model=model)

mcp_servers_cli/backends/anthropic.py

@@ -0,0 +1,86 @@
+"""Anthropic backend: the Messages API. Optional dependency, `mcp-servers-cli[anthropic]`."""
+
+from collections.abc import Sequence
+from typing import Any
+
+import anthropic
+from anthropic.types import Message as AnthropicMessage
+
+from mcp_servers_cli.llm import Message, ToolCall, ToolSpec
+
+DEFAULT_MAX_TOKENS = 4096
+
+
+def to_anthropic_tool(tool: ToolSpec) -> dict[str, Any]:
+    return {
+        "name": tool.name,
+        "description": tool.description,
+        "input_schema": tool.input_schema or {"type": "object", "properties": {}},
+    }
+
+
+def to_anthropic_messages(messages: Sequence[Message]) -> list[dict[str, Any]]:
+    """Results go back in a user turn, each paired with its call by `tool_use_id`."""
+    converted: list[dict[str, Any]] = []
+    for message in messages:
+        if message.role == "tool":
+            blocks = [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": result.call_id,
+                    "content": result.content,
+                    "is_error": result.is_error,
+                }
+                for result in message.tool_results
+            ]
+            converted.append({"role": "user", "content": blocks})
+        elif message.role == "assistant":
+            blocks = [{"type": "text", "text": message.text}] if message.text else []
+            blocks += [
+                {"type": "tool_use", "id": call.id, "name": call.name, "input": call.arguments}
+                for call in message.tool_calls
+            ]
+            converted.append({"role": "assistant", "content": blocks})
+        else:
+            converted.append({"role": "user", "content": message.text})
+    return converted
+
+
+def from_anthropic_message(message: AnthropicMessage) -> Message:
+    text = "".join(block.text for block in message.content if block.type == "text")
+    calls = tuple(
+        ToolCall(id=block.id, name=block.name, arguments=dict(block.input))
+        for block in message.content
+        if block.type == "tool_use"
+    )
+    return Message(role="assistant", text=text, tool_calls=calls)
+
+
+class AnthropicBackend:
+    """Reads ANTHROPIC_API_KEY from the environment, never from the command line."""
+
+    def __init__(
+        self,
+        model: str,
+        client: anthropic.AsyncAnthropic | None = None,
+        max_tokens: int = DEFAULT_MAX_TOKENS,
+    ) -> None:
+        self.model = model
+        self.max_tokens = max_tokens
+        self._client = client or anthropic.AsyncAnthropic()
+
+    async def complete(
+        self, system: str, messages: Sequence[Message], tools: Sequence[ToolSpec]
+    ) -> Message:
+        optional: dict[str, Any] = {}
+        if system:
+            optional["system"] = system
+        if tools:
+            optional["tools"] = [to_anthropic_tool(tool) for tool in tools]
+        response = await self._client.messages.create(
+            model=self.model,
+            max_tokens=self.max_tokens,
+            messages=to_anthropic_messages(messages),
+            **optional,
+        )
+        return from_anthropic_message(response)

mcp_servers_cli/backends/ollama.py

@@ -0,0 +1,94 @@
+"""Ollama backend: local models through the official async client."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import ollama
+
+from mcp_servers_cli.llm import Message, ToolCall, ToolSpec
+
+SCHEMA_KEYS = {"type", "value", "description"}
+
+
+def normalize_args(args: Mapping[str, Any]) -> dict[str, Any]:
+    """Unwrap values some local models wrap in their schema: {'type': 'string', 'value': 'x'}.
+
+    Only dicts made of schema keys are unwrapped, so a genuine nested object is left intact.
+    """
+    return {
+        key: value["value"]
+        if isinstance(value, dict) and "value" in value and set(value) <= SCHEMA_KEYS
+        else value
+        for key, value in args.items()
+    }
+
+
+def to_ollama_tool(tool: ToolSpec) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": tool.input_schema or {"type": "object", "properties": {}},
+        },
+    }
+
+
+def to_ollama_messages(system: str, messages: Sequence[Message]) -> list[dict[str, Any]]:
+    """Ollama pairs a result with its call by position: one tool message per result, in order."""
+    converted: list[dict[str, Any]] = [{"role": "system", "content": system}] if system else []
+    for message in messages:
+        if message.role == "tool":
+            converted.extend(
+                {
+                    "role": "tool",
+                    "tool_name": result.name,
+                    "content": f"error: {result.content}" if result.is_error else result.content,
+                }
+                for result in message.tool_results
+            )
+        elif message.tool_calls:
+            converted.append(
+                {
+                    "role": "assistant",
+                    "content": message.text,
+                    "tool_calls": [
+                        {"function": {"name": call.name, "arguments": call.arguments}}
+                        for call in message.tool_calls
+                    ],
+                }
+            )
+        else:
+            converted.append({"role": message.role, "content": message.text})
+    return converted
+
+
+def from_ollama_message(message: ollama.Message) -> Message:
+    """Ollama calls carry no id: number them so their results can be paired back."""
+    calls = tuple(
+        ToolCall(
+            id=f"call_{index}",
+            name=call.function.name,
+            arguments=normalize_args(call.function.arguments or {}),
+        )
+        for index, call in enumerate(message.tool_calls or [])
+    )
+    return Message(role="assistant", text=message.content or "", tool_calls=calls)
+
+
+class OllamaBackend:
+    """Talks to the Ollama server named by OLLAMA_HOST, localhost by default."""
+
+    def __init__(self, model: str, client: ollama.AsyncClient | None = None) -> None:
+        self.model = model
+        self._client = client or ollama.AsyncClient()
+
+    async def complete(
+        self, system: str, messages: Sequence[Message], tools: Sequence[ToolSpec]
+    ) -> Message:
+        response = await self._client.chat(
+            model=self.model,
+            messages=to_ollama_messages(system, messages),
+            tools=[to_ollama_tool(tool) for tool in tools],
+        )
+        return from_ollama_message(response.message)

mcp_servers_cli/cli.py

@@ -0,0 +1,233 @@
+"""Command line entry point. One command per action, the target given as an option."""
+
+import json
+import os
+import sys
+import time
+from importlib import metadata
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import App, Group, Parameter
+from fastmcp import Client
+from rich.console import Console
+from rich.markup import escape
+
+from mcp_servers_cli.agent import DEFAULT_MAX_STEPS, first_turn, run_agent
+from mcp_servers_cli.backends import BACKENDS, create_backend
+from mcp_servers_cli.errors import DEBUG_ENV_VAR, describe
+from mcp_servers_cli.inspection import inspect_server
+from mcp_servers_cli.llm import LLMBackend, ToolCall, ToolResult
+from mcp_servers_cli.rendering import (
+    render_answer,
+    render_blocks,
+    render_failures,
+    render_plan,
+    render_server,
+    render_tool_call,
+    render_tool_result,
+)
+from mcp_servers_cli.repl import run_repl
+from mcp_servers_cli.trace import Trace, open_trace
+from mcp_servers_cli.transports import config_client, http_client, stdio_client
+
+app = App(
+    name="mcp-servers-cli",
+    help="Inspect, call and drive any MCP server.",
+    version=metadata.version("mcp-servers-cli"),
+)
+
+TARGET = Group("Target", help="Exactly one transport must be given.")
+
+Stdio = Annotated[str | None, Parameter(group=TARGET, help="Command launching the server.")]
+Http = Annotated[str | None, Parameter(group=TARGET, help="URL of a remote server.")]
+Config = Annotated[str | None, Parameter(group=TARGET, help="Path to an mcpServers JSON file.")]
+Server = Annotated[str | None, Parameter(group=TARGET, help="Server name inside --config.")]
+Env = Annotated[list[str] | None, Parameter(help="KEY=VALUE passed to a stdio subprocess.")]
+Quiet = Annotated[bool, Parameter(help="Hide the inspected server's own stderr output.")]
+
+
+def build_client(
+    stdio: str | None,
+    http: str | None,
+    config: str | None,
+    server: str | None,
+    env: list[str] | None,
+    quiet: bool = False,
+) -> Client:
+    """Resolve the mutually exclusive target options into a Client."""
+    chosen = [
+        name for name, value in (("stdio", stdio), ("http", http), ("config", config)) if value
+    ]
+    if len(chosen) != 1:
+        raise ValueError("Give exactly one of --stdio, --http or --config.")
+
+    if stdio:
+        return stdio_client(
+            stdio,
+            env=dict(item.split("=", 1) for item in env) if env else None,
+            log_file=Path(os.devnull) if quiet else None,
+        )
+    if http:
+        return http_client(http)
+    if not server:
+        raise ValueError("--config requires --server.")
+    return config_client(config, server)
+
+
+@app.command
+async def inspect(
+    *,
+    stdio: Stdio = None,
+    http: Http = None,
+    config: Config = None,
+    server: Server = None,
+    env: Env = None,
+    quiet: Quiet = False,
+) -> None:
+    """List the tools, resources and prompts a server exposes."""
+    async with build_client(stdio, http, config, server, env, quiet) as client:
+        render_server(await inspect_server(client))
+
+
+@app.command
+async def call(
+    tool: str,
+    arguments: str = "{}",
+    *,
+    stdio: Stdio = None,
+    http: Http = None,
+    config: Config = None,
+    server: Server = None,
+    env: Env = None,
+    quiet: Quiet = False,
+) -> None:
+    """Call one tool with JSON arguments and print the result."""
+    async with build_client(stdio, http, config, server, env, quiet) as client:
+        result = await client.call_tool(tool, json.loads(arguments))
+        render_blocks(result.content)
+
+
+@app.command
+async def read(
+    uri: str,
+    *,
+    stdio: Stdio = None,
+    http: Http = None,
+    config: Config = None,
+    server: Server = None,
+    env: Env = None,
+    quiet: Quiet = False,
+) -> None:
+    """Read one resource and print its content."""
+    async with build_client(stdio, http, config, server, env, quiet) as client:
+        render_blocks(await client.read_resource(uri))
+
+
+@app.command
+async def repl(
+    *,
+    stdio: Stdio = None,
+    http: Http = None,
+    config: Config = None,
+    server: Server = None,
+    env: Env = None,
+    quiet: Quiet = False,
+) -> None:
+    """Inspect a server, then take commands interactively."""
+    async with build_client(stdio, http, config, server, env, quiet) as client:
+        render_server(await inspect_server(client))
+        await run_repl(client)
+
+
+@app.command
+async def agent(
+    prompt: str,
+    *,
+    model: Annotated[str, Parameter(help="Model name, e.g. qwen3.5:4b or claude-sonnet-5.")],
+    backend: Annotated[
+        str, Parameter(help=f"LLM backend: {', '.join(sorted(BACKENDS))}.")
+    ] = "ollama",
+    system: Annotated[str, Parameter(help="System prompt given to the model.")] = "",
+    max_steps: Annotated[int, Parameter(help="Model turns allowed before giving up.")] = (
+        DEFAULT_MAX_STEPS
+    ),
+    trace: Annotated[
+        Path | None, Parameter(help="Write every tool call to this JSONL file.")
+    ] = None,
+    dry_run: Annotated[bool, Parameter(help="Show the model's first calls, run none.")] = False,
+    stdio: Stdio = None,
+    http: Http = None,
+    config: Config = None,
+    server: Server = None,
+    env: Env = None,
+    quiet: Quiet = False,
+) -> None:
+    """Let a model use the server's tools to answer a prompt."""
+    llm = create_backend(backend, model)
+    with open_trace(trace) as recorder:
+        async with build_client(stdio, http, config, server, env, quiet) as client:
+            if dry_run:
+                await _plan(client, llm, prompt, system, recorder)
+            else:
+                await _solve(client, llm, prompt, system, max_steps, recorder)
+
+
+async def _plan(client: Client, llm: LLMBackend, prompt: str, system: str, recorder: Trace) -> None:
+    """--dry-run: one model turn, every requested call shown and none executed."""
+    started = time.perf_counter()
+    reply = await first_turn(client, llm, prompt, system=system)
+    for call in reply.tool_calls:
+        recorder.planned(call)
+    recorder.end(steps=1, stopped=False, answer=reply.text, elapsed=time.perf_counter() - started)
+    if reply.tool_calls:
+        render_plan(reply.tool_calls)
+    else:
+        render_answer(reply.text)
+
+
+async def _solve(
+    client: Client, llm: LLMBackend, prompt: str, system: str, max_steps: int, recorder: Trace
+) -> None:
+    """The full run: every call printed and recorded as it happens, then the answer."""
+
+    def on_tool_result(call: ToolCall, result: ToolResult, elapsed: float) -> None:
+        render_tool_result(call, result, elapsed)
+        recorder.tool(call, result, elapsed)
+
+    started = time.perf_counter()
+    run = await run_agent(
+        client,
+        llm,
+        prompt,
+        system=system,
+        max_steps=max_steps,
+        on_tool_call=render_tool_call,
+        on_tool_result=on_tool_result,
+    )
+    recorder.end(
+        steps=run.steps,
+        stopped=run.stopped,
+        answer=run.answer,
+        elapsed=time.perf_counter() - started,
+        tool_calls=len(run.results),
+        failed_calls=run.failed,
+    )
+    if run.stopped:
+        raise RuntimeError(f"no final answer after {max_steps} model turns (see --max-steps)")
+    render_answer(run.answer)
+    if run.failed:
+        render_failures(run.failed, len(run.results))
+
+
+def main(tokens: list[str] | None = None) -> None:
+    """Console entry point: one line per failure, the full trace when the debug variable is set."""
+    try:
+        app(tokens)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as exc:
+        if os.environ.get(DEBUG_ENV_VAR):
+            raise
+        Console(stderr=True, soft_wrap=True).print(f"[red]error:[/red] {escape(describe(exc))}")
+        sys.exit(1)

mcp_servers_cli/errors.py

@@ -0,0 +1,30 @@
+"""Turning a failure into the one line a terminal user needs. The full trace stays opt-in."""
+
+import json
+
+from mcp.shared.exceptions import MCPError
+from mcp.types import CONNECTION_CLOSED
+
+DEBUG_ENV_VAR = "MCP_SERVERS_CLI_DEBUG"
+
+
+def leaf(exc: BaseException) -> BaseException:
+    """First innermost exception of nested exception groups, as raised by anyio task groups."""
+    seen: set[int] = set()
+    while isinstance(exc, BaseExceptionGroup) and exc.exceptions and id(exc) not in seen:
+        seen.add(id(exc))
+        exc = exc.exceptions[0]
+    return exc
+
+
+def describe(exc: BaseException) -> str:
+    """One line naming the cause, without the stack."""
+    exc = leaf(exc)
+    if isinstance(exc, MCPError) and exc.code == CONNECTION_CLOSED:
+        return (
+            "the server closed the connection: its own error output above gives the cause "
+            "(hidden if --quiet was given)"
+        )
+    if isinstance(exc, json.JSONDecodeError):
+        return f"invalid JSON: {exc}"
+    return str(exc) or type(exc).__name__