casual-mcp 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

casual_mcp/models/config.py

@@ -1,10 +1,12 @@
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from casual_mcp.models.mcp_server_config import McpServerConfig
 from casual_mcp.models.model_config import McpModelConfig
+from casual_mcp.models.toolset_config import ToolSetConfig
 
 
 class Config(BaseModel):
     namespace_tools: bool | None = False
     models: dict[str, McpModelConfig]
     servers: dict[str, McpServerConfig]
+    tool_sets: dict[str, ToolSetConfig] = Field(default_factory=dict)

casual_mcp/models/toolset_config.py

@@ -0,0 +1,40 @@
+"""Toolset configuration models for filtering available tools."""
+
+from pydantic import BaseModel, Field
+
+
+class ExcludeSpec(BaseModel):
+    """Specification for excluding specific tools from a server."""
+
+    exclude: list[str] = Field(description="List of tool names to exclude")
+
+
+# Tool specification: true (all), list (include specific), or exclude object
+ToolSpec = bool | list[str] | ExcludeSpec
+
+
+class ToolSetConfig(BaseModel):
+    """Configuration for a named toolset.
+
+    A toolset defines which tools from which servers should be available
+    during a chat session. Each server can be configured to:
+    - Include all tools (True)
+    - Include specific tools (list of tool names)
+    - Include all except specific tools (ExcludeSpec)
+
+    Example:
+        {
+            "description": "Research tools",
+            "servers": {
+                "wikimedia": True,
+                "search": ["brave_web_search"],
+                "fetch": {"exclude": ["fetch_dangerous"]}
+            }
+        }
+    """
+
+    description: str = Field(default="", description="Human-readable description")
+    servers: dict[str, ToolSpec] = Field(
+        default_factory=dict,
+        description="Mapping of server name to tool specification",
+    )

casual_mcp/tool_filter.py

@@ -0,0 +1,171 @@
+"""Tool filtering logic for toolsets.
+
+This module provides functionality to filter MCP tools based on toolset
+configurations, including validation to ensure referenced servers and
+tools actually exist.
+"""
+
+import mcp
+
+from casual_mcp.logging import get_logger
+from casual_mcp.models.toolset_config import ExcludeSpec, ToolSetConfig
+
+logger = get_logger("tool_filter")
+
+
+class ToolSetValidationError(Exception):
+    """Raised when a toolset references invalid servers or tools."""
+
+    pass
+
+
+def extract_server_and_tool(tool_name: str, server_names: set[str]) -> tuple[str, str]:
+    """Extract server name and base tool name from a potentially prefixed tool name.
+
+    When multiple servers are configured, fastmcp prefixes tools as "serverName_toolName".
+    When a single server is configured, tools are not prefixed.
+
+    Args:
+        tool_name: The full tool name (possibly prefixed)
+        server_names: Set of configured server names
+
+    Returns:
+        Tuple of (server_name, base_tool_name)
+    """
+    if "_" in tool_name:
+        prefix = tool_name.split("_", 1)[0]
+        if prefix in server_names:
+            return prefix, tool_name.split("_", 1)[1]
+
+    # Single server case - return the single server name
+    if len(server_names) == 1:
+        return next(iter(server_names)), tool_name
+
+    # Fallback - can't determine server
+    return "default", tool_name
+
+
+def _build_server_tool_map(tools: list[mcp.Tool], server_names: set[str]) -> dict[str, set[str]]:
+    """Build a mapping of server names to their available tool names.
+
+    Args:
+        tools: List of MCP tools
+        server_names: Set of configured server names
+
+    Returns:
+        Dict mapping server name to set of base tool names
+    """
+    server_tool_map: dict[str, set[str]] = {name: set() for name in server_names}
+
+    for tool in tools:
+        server_name, base_name = extract_server_and_tool(tool.name, server_names)
+        if server_name in server_tool_map:
+            server_tool_map[server_name].add(base_name)
+
+    return server_tool_map
+
+
+def validate_toolset(
+    toolset: ToolSetConfig,
+    tools: list[mcp.Tool],
+    server_names: set[str],
+) -> None:
+    """Validate that a toolset references only valid servers and tools.
+
+    Args:
+        toolset: The toolset configuration to validate
+        tools: List of available MCP tools
+        server_names: Set of configured server names
+
+    Raises:
+        ToolSetValidationError: If the toolset references non-existent servers or tools
+    """
+    server_tool_map = _build_server_tool_map(tools, server_names)
+    errors: list[str] = []
+
+    for server_name, tool_spec in toolset.servers.items():
+        # Check server exists
+        if server_name not in server_names:
+            errors.append(f"Server '{server_name}' not found in configuration")
+            continue
+
+        available = server_tool_map.get(server_name, set())
+
+        # Validate tool names in include list
+        if isinstance(tool_spec, list):
+            for tool_name in tool_spec:
+                if tool_name not in available:
+                    errors.append(
+                        f"Tool '{tool_name}' not found in server '{server_name}'. "
+                        f"Available: {sorted(available)}"
+                    )
+
+        # Validate tool names in exclude list
+        elif isinstance(tool_spec, ExcludeSpec):
+            for tool_name in tool_spec.exclude:
+                if tool_name not in available:
+                    errors.append(
+                        f"Tool '{tool_name}' not found in server '{server_name}' "
+                        f"(specified in exclude list). Available: {sorted(available)}"
+                    )
+
+    if errors:
+        raise ToolSetValidationError("\n".join(errors))
+
+
+def filter_tools_by_toolset(
+    tools: list[mcp.Tool],
+    toolset: ToolSetConfig,
+    server_names: set[str],
+    validate: bool = True,
+) -> list[mcp.Tool]:
+    """Filter a list of MCP tools based on a toolset configuration.
+
+    Args:
+        tools: Full list of available MCP tools
+        toolset: The toolset configuration to apply
+        server_names: Set of configured server names
+        validate: Whether to validate the toolset first (raises on invalid)
+
+    Returns:
+        Filtered list of tools matching the toolset
+
+    Raises:
+        ToolSetValidationError: If validate=True and toolset is invalid
+    """
+    if validate:
+        validate_toolset(toolset, tools, server_names)
+
+    filtered: list[mcp.Tool] = []
+
+    for tool in tools:
+        server_name, base_name = extract_server_and_tool(tool.name, server_names)
+
+        # Check if this server is in the toolset
+        if server_name not in toolset.servers:
+            continue
+
+        tool_spec = toolset.servers[server_name]
+
+        # Determine if tool should be included
+        include = False
+
+        if tool_spec is True:
+            # All tools from this server
+            include = True
+        elif isinstance(tool_spec, list):
+            # Only specific tools
+            include = base_name in tool_spec
+        elif isinstance(tool_spec, ExcludeSpec):
+            # All except excluded tools
+            include = base_name not in tool_spec.exclude
+
+        if include:
+            filtered.append(tool)
+
+    logger.debug(
+        f"Filtered {len(tools)} tools to {len(filtered)} using toolset "
+        f"with {len(toolset.servers)} servers"
+    )
+
+    return filtered

casual_mcp-0.7.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: casual-mcp
+Version: 0.7.0
+Summary: Multi-server MCP client for LLM tool orchestration
+Author: Alex Stansfield
+License: MIT
+Project-URL: Homepage, https://github.com/casualgenius/casual-mcp
+Project-URL: Repository, https://github.com/casualgenius/casual-mcp
+Project-URL: Issue Tracker, https://github.com/casualgenius/casual-mcp/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: casual-llm[openai]>=0.4.3
+Requires-Dist: dateparser>=1.2.1
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: fastmcp>=2.12.4
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: rich>=14.0.0
+Requires-Dist: typer>=0.19.2
+Requires-Dist: uvicorn>=0.34.2
+Dynamic: license-file
+
+# Casual MCP
+
+![PyPI](https://img.shields.io/pypi/v/casual-mcp)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+
+**Casual MCP** is a Python framework for building, evaluating, and serving LLMs with tool-calling capabilities using [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
+
+## Features
+
+- Multi-server MCP client using [FastMCP](https://github.com/jlowin/fastmcp)
+- OpenAI and Ollama provider support (via [casual-llm](https://github.com/AlexStansfield/casual-llm))
+- Recursive tool-calling chat loop
+- Toolsets for selective tool filtering per request
+- Usage statistics tracking (tokens, tool calls, LLM calls)
+- System prompt templating with Jinja2
+- CLI and API interfaces
+
+## Installation
+
+```bash
+# Using uv
+uv add casual-mcp
+
+# Using pip
+pip install casual-mcp
+```
+
+For development:
+
+```bash
+git clone https://github.com/casualgenius/casual-mcp.git
+cd casual-mcp
+uv sync --group dev
+```
+
+## Quick Start
+
+1. Create `casual_mcp_config.json`:
+
+```json
+{
+  "models": {
+    "gpt-4.1": { "provider": "openai", "model": "gpt-4.1" }
+  },
+  "servers": {
+    "time": { "command": "python", "args": ["mcp-servers/time/server.py"] }
+  }
+}
+```
+
+2. Set your API key: `export OPENAI_API_KEY=your-key`
+
+3. Start the server: `casual-mcp serve`
+
+4. Make a request:
+
+```bash
+curl -X POST http://localhost:8000/generate \
+  -H "Content-Type: application/json" \
+  -d '{"model": "gpt-4.1", "prompt": "What time is it?"}'
+```
+
+## Configuration
+
+Configure models, MCP servers, and toolsets in `casual_mcp_config.json`.
+
+```json
+{
+  "models": {
+    "gpt-4.1": { "provider": "openai", "model": "gpt-4.1" }
+  },
+  "servers": {
+    "time": { "command": "python", "args": ["server.py"] },
+    "weather": { "url": "http://localhost:5050/mcp" }
+  },
+  "tool_sets": {
+    "basic": { "description": "Basic tools", "servers": { "time": true } }
+  }
+}
+```
+
+See [Configuration Guide](docs/configuration.md) for full details on models, servers, toolsets, and templates.
+
+## CLI
+
+```bash
+casual-mcp serve              # Start API server
+casual-mcp servers            # List configured servers
+casual-mcp models             # List configured models
+casual-mcp toolsets           # Manage toolsets interactively
+casual-mcp tools              # List available tools
+```
+
+See [CLI & API Reference](docs/cli-api.md) for all commands and options.
+
+## API
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /chat` | Send message history |
+| `POST /generate` | Send prompt with optional session |
+| `GET /generate/session/{id}` | Get session messages |
+| `GET /toolsets` | List available toolsets |
+
+See [CLI & API Reference](docs/cli-api.md#api-endpoints) for request/response formats.
+
+## Programmatic Usage
+
+```python
+from casual_llm import SystemMessage, UserMessage
+from casual_mcp import McpToolChat, ProviderFactory, load_config, load_mcp_client
+
+config = load_config("casual_mcp_config.json")
+mcp_client = load_mcp_client(config)
+
+provider_factory = ProviderFactory()
+provider = provider_factory.get_provider("gpt-4.1", config.models["gpt-4.1"])
+
+chat = McpToolChat(mcp_client, provider)
+messages = [
+    SystemMessage(content="You are a helpful assistant."),
+    UserMessage(content="What time is it?")
+]
+response = await chat.chat(messages)
+```
+
+See [Programmatic Usage Guide](docs/programmatic-usage.md) for `McpToolChat`, usage statistics, toolsets, and common patterns.
+
+## Architecture
+
+Casual MCP orchestrates LLMs and MCP tool servers in a recursive loop:
+
+```
+┌─────────────┐      ┌──────────────┐      ┌─────────────┐
+│ MCP Servers │─────▶│  Tool Cache  │─────▶│ Tool Converter│
+└─────────────┘      └──────────────┘      └─────────────┘
+                            │                      │
+                            ▼                      ▼
+                     ┌──────────────────────────────┐
+                     │     McpToolChat Loop         │
+                     │                              │
+                     │  LLM ──▶ Tool Calls ──▶ MCP  │
+                     │   ▲                      │   │
+                     │   └──────── Results ─────┘   │
+                     └──────────────────────────────┘
+```
+
+1. **MCP Client** connects to tool servers (local stdio or remote HTTP/SSE)
+2. **Tool Cache** fetches and caches tools from all servers
+3. **ProviderFactory** creates LLM providers from casual-llm
+4. **McpToolChat** runs the recursive loop until the LLM provides a final answer
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENAI_API_KEY` | - | Required for OpenAI provider |
+| `TOOL_RESULT_FORMAT` | `result` | `result`, `function_result`, or `function_args_result` |
+| `MCP_TOOL_CACHE_TTL` | `30` | Tool cache TTL in seconds (0 = indefinite) |
+| `LOG_LEVEL` | `INFO` | Logging level |
+
+## Troubleshooting
+
+Common issues and solutions are covered in the [Troubleshooting Guide](docs/troubleshooting.md).
+
+## License
+
+[MIT License](LICENSE)

{casual_mcp-0.6.0.dist-info → casual_mcp-0.7.0.dist-info}/RECORD

@@ -1,21 +1,23 @@
 casual_mcp/__init__.py,sha256=eeI1TIj8Cu-H4OMV64LaNqVqo4wSFaGu7215hJeN_HM,598
-casual_mcp/cli.py,sha256=2-0sTxfNfQSukBtg0Xs9P6VrAMZ89SqJ9VJzOM68d-o,2129
+casual_mcp/cli.py,sha256=yzNkS2rZ8Lb-1nGFY75RUaixHf1x-vf6gdUPU58jOlg,14953
 casual_mcp/convert_tools.py,sha256=mlH18DTGGeWb0Vxfj1cUSMhTGRE9z8q_xWrVXvpg3mE,1742
 casual_mcp/logging.py,sha256=S2XpLIKHHDtmru_YBFLdMamdmYRm16Yw3tshE3g3Wqg,932
-casual_mcp/main.py,sha256=aI3isW0Wzny_iubx8HlNgBVvYEeBe-Jrrdbp80oYmk4,4299
-casual_mcp/mcp_tool_chat.py,sha256=Evc5LMfUYicl7jlix42QURYaq0cI2CIUg0q-344cjUg,8401
+casual_mcp/main.py,sha256=OxW6itdauq23QyxPhCt6K0kM2jV2WlP_JSfk5IKSN48,6057
+casual_mcp/mcp_tool_chat.py,sha256=h9-1wzgLIhm6kfaNHNJ3RGwkL3A3Q3EoUZvnxIroL74,11144
 casual_mcp/provider_factory.py,sha256=Jp2HQOJdlDDed-hfZf1drEVbw0kpZSE0TN9G0Dcp4w8,1260
 casual_mcp/tool_cache.py,sha256=VE599sF7vHH6megcueqVxCZavvTcoFDoZu2QuZM3cYA,3161
+casual_mcp/tool_filter.py,sha256=u1C8w0CNZ4AH4bbkIRz0ph9-g9-OxSBnkZiLJVapyHo,5430
 casual_mcp/utils.py,sha256=XxzPxQ3j97edeCRXtoO8lJS9R0JYOa25p2MJNwGapJA,3201
-casual_mcp/models/__init__.py,sha256=byhteS6fueIdtoaQYL2w5hcBJmJhXF7X7YhGslvscco,786
+casual_mcp/models/__init__.py,sha256=2D3grALibdsymdpI82EHVGCgEKCszU418qh61os7_rM,924
 casual_mcp/models/chat_stats.py,sha256=ZjeZ_ckx-SfioYs39NAaQxK6qPG9SlFlrB7j7jHZ40w,1221
-casual_mcp/models/config.py,sha256=LcqtfW3w7iqrT3FnW50L1mgqAvD_OsYk4ySBZZVV-GI,300
+casual_mcp/models/config.py,sha256=JsgRtZzA3jZALfAKj-nMIJjnd4RmGmJsLUdzQ_6wCZk,436
 casual_mcp/models/generation_error.py,sha256=abDAahS2fhYkS-ARng1Tk7oudoAO4imkoKYcC9PHT2U,272
 casual_mcp/models/mcp_server_config.py,sha256=0OHsHUEKxRoCl21lsye4E5GoCNmdZWIZCOOthcTpdsE,539
 casual_mcp/models/model_config.py,sha256=59Y7MvcboPKdAilSwUyeC7lfRm4aYkFhZ5c8EVRP5ys,425
-casual_mcp-0.6.0.dist-info/licenses/LICENSE,sha256=U3Zu2tkrh5vXdy7gIdE8WJGM9D4gGp3hohAAWdre-yo,1058
-casual_mcp-0.6.0.dist-info/METADATA,sha256=GQLuEXfducugyuUHjB3qklz8FAOZ7go3PQ0d7Pqb2ZI,22218
-casual_mcp-0.6.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-casual_mcp-0.6.0.dist-info/entry_points.txt,sha256=X48Np2cwl-SlRQdV26y2vPZ-2tJaODgZeVtfpHho-zg,50
-casual_mcp-0.6.0.dist-info/top_level.txt,sha256=K4CiI0Jf8PHICjuQVm32HuNMB44kp8Lb02bbbdiH5bo,11
-casual_mcp-0.6.0.dist-info/RECORD,,
+casual_mcp/models/toolset_config.py,sha256=k95TqhHXYDonAt0GG5akzZRWzQ6rZG77eLB7QlSV5AA,1246
+casual_mcp-0.7.0.dist-info/licenses/LICENSE,sha256=U3Zu2tkrh5vXdy7gIdE8WJGM9D4gGp3hohAAWdre-yo,1058
+casual_mcp-0.7.0.dist-info/METADATA,sha256=8S2ssCaPlmVS3zYobzuzRKsLSyyKP_QHzjRCAtfdP80,6211
+casual_mcp-0.7.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+casual_mcp-0.7.0.dist-info/entry_points.txt,sha256=X48Np2cwl-SlRQdV26y2vPZ-2tJaODgZeVtfpHho-zg,50
+casual_mcp-0.7.0.dist-info/top_level.txt,sha256=K4CiI0Jf8PHICjuQVm32HuNMB44kp8Lb02bbbdiH5bo,11
+casual_mcp-0.7.0.dist-info/RECORD,,