matimo-core 0.2.0__tar.gz → 0.4.0__tar.gz

{matimo_core-0.2.0 → matimo_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matimo-core
-Version: 0.2.0
+Version: 0.4.0
 Summary: Matimo core — framework-agnostic SDK: pre-built providers, skills layer, MCP, and a policy engine you control
 Project-URL: Homepage, https://matimo.dev
 Project-URL: Documentation, https://docs.matimo.dev/
@@ -39,7 +39,7 @@ Requires-Dist: agno>=3.0; extra == 'all'
 Requires-Dist: crewai>=0.80; extra == 'all'
 Requires-Dist: hvac>=2.0; extra == 'all'
 Requires-Dist: langchain-core>=0.3; extra == 'all'
-Requires-Dist: mcp>=1.28.1; extra == 'all'
+Requires-Dist: mcp>=2.0; extra == 'all'
 Requires-Dist: python-dotenv>=1.0; extra == 'all'
 Provides-Extra: aws
 Requires-Dist: boto3>=1.34; extra == 'aws'
@@ -51,7 +51,7 @@ Requires-Dist: boto3>=1.34; extra == 'dev'
 Requires-Dist: crewai>=0.80; extra == 'dev'
 Requires-Dist: hvac>=2.0; extra == 'dev'
 Requires-Dist: langchain-core>=0.3; extra == 'dev'
-Requires-Dist: mcp>=1.28.1; extra == 'dev'
+Requires-Dist: mcp>=2.0; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
@@ -65,7 +65,7 @@ Requires-Dist: python-dotenv>=1.0; extra == 'dotenv'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.3; extra == 'langchain'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.28.1; extra == 'mcp'
+Requires-Dist: mcp>=2.0; extra == 'mcp'
 Provides-Extra: vault
 Requires-Dist: hvac>=2.0; extra == 'vault'
 Description-Content-Type: text/markdown

{matimo_core-0.2.0 → matimo_core-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matimo-core"
-version = "0.2.0"
+version = "0.4.0"
 description = "Matimo core — framework-agnostic SDK: pre-built providers, skills layer, MCP, and a policy engine you control"
 readme = "README.md"
 license = { text = "MIT" }
@@ -41,7 +41,7 @@ dependencies = [
 langchain = ["langchain-core>=0.3"]
 crewai = ["crewai>=0.80"]
 agno = ["agno>=3.0"]
-mcp = ["mcp>=1.28.1"]
+mcp = ["mcp>=2.0"]
 vault = ["hvac>=2.0"]
 aws = ["boto3>=1.34"]
 dotenv = ["python-dotenv>=1.0"]
@@ -49,7 +49,7 @@ all = [
     "langchain-core>=0.3",
     "crewai>=0.80",
     "agno>=3.0",
-    "mcp>=1.28.1",
+    "mcp>=2.0",
     "hvac>=2.0",
     "python-dotenv>=1.0",
 ]
@@ -64,7 +64,7 @@ dev = [
     "langchain-core>=0.3",
     "crewai>=0.80",
     "agno>=3.0",
-    "mcp>=1.28.1",
+    "mcp>=2.0",
     "hvac>=2.0",
     "boto3>=1.34",
     "python-dotenv>=1.0",

{matimo_core-0.2.0 → matimo_core-0.4.0}/src/matimo/__init__.py

@@ -185,7 +185,7 @@ from matimo.policy.types import (
 )
 from matimo.sync import MatimoSync
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 
 def get_core_tools_path() -> str:

{matimo_core-0.2.0 → matimo_core-0.4.0}/src/matimo/approval/handler.py

@@ -23,6 +23,10 @@ DEFAULT_DESTRUCTIVE_KEYWORDS: list[str] = [
     "INSERT", "UPSERT", "REPLACE", "MERGE", "GRANT", "REVOKE",
     "EDIT", "WRITE", "APPEND", "REMOVE", "PURGE", "RENAME", "SHUTDOWN",
     "EXECUTE", "EXEC",
+    # SQL escape hatches: file/OS/remote access and session control, even inside a SELECT
+    "COPY", "PROGRAM", "CALL", "DO $$", "DO LANGUAGE", "VACUUM", "REINDEX", "PG_READ_FILE",
+    "PG_READ_BINARY_FILE", "PG_LS_DIR", "PG_STAT_FILE", "LO_IMPORT", "LO_EXPORT", "DBLINK",
+    "SET_CONFIG", "PG_TERMINATE_BACKEND", "PG_CANCEL_BACKEND",
 ]
 
 
@@ -33,6 +37,22 @@ DEFAULT_DESTRUCTIVE_KEYWORDS: list[str] = [
 NEVER_PRE_APPROVED_TOOLS: frozenset[str] = frozenset({"matimo_approve_tool"})
 
 
+def requires_mandatory_human_approval(
+    tool_name: str, params: dict[str, Any] | None = None
+) -> bool:
+    """
+    Whether this particular call needs a human decision that nothing may skip:
+    neither MATIMO_AUTO_APPROVE, an approved pattern (not even "*"), nor a
+    caller-supplied `approved=True`. `execute` with a `shell` runs its command
+    through that shell, where metacharacters are live, so every such call is
+    shown to a human. Mirrors requiresMandatoryHumanApproval() in approval-handler.ts.
+    """
+    if tool_name != "execute" or not params:
+        return False
+    shell = params.get("shell")
+    return shell is not None and shell != ""
+
+
 def definition_requires_approval(tool: ToolDefinition, mode: GovernanceMode = "secure") -> bool:
     """
     Whether a tool's definition alone makes every call need approval.
@@ -112,10 +132,12 @@ class ApprovalHandler:
             return any(kw in upper for kw in self.destructive_keywords)
         return False
 
-    def is_pre_approved(self, tool_name: str) -> bool:
+    def is_pre_approved(self, tool_name: str, params: dict[str, Any] | None = None) -> bool:
         """True when MATIMO_AUTO_APPROVE is on or the tool matches an approved pattern.
-        Never for NEVER_PRE_APPROVED_TOOLS."""
-        if tool_name in NEVER_PRE_APPROVED_TOOLS:
+        Never for NEVER_PRE_APPROVED_TOOLS or a call needing mandatory human approval."""
+        if tool_name in NEVER_PRE_APPROVED_TOOLS or requires_mandatory_human_approval(
+            tool_name, params
+        ):
             return False
         return self.auto_approve or self._matches_approved_pattern(tool_name)
 
@@ -131,7 +153,7 @@ class ApprovalHandler:
         callback = callback if callback is not None else self._callback
         # 1-2. MATIMO_AUTO_APPROVE (CI / testing) or an approved pattern —
         # never for NEVER_PRE_APPROVED_TOOLS
-        if self.is_pre_approved(request.tool_name):
+        if self.is_pre_approved(request.tool_name, request.params):
             logger.debug(
                 "Tool '%s' is pre-approved (MATIMO_AUTO_APPROVE or approved pattern)",
                 request.tool_name,

{matimo_core-0.2.0 → matimo_core-0.4.0}/src/matimo/decorators/__init__.py

@@ -13,6 +13,7 @@ Usage:
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import functools
 import inspect
 import logging
@@ -25,6 +26,11 @@ if TYPE_CHECKING:
 logger = logging.getLogger("matimo")
 
 _global_instance: Matimo | None = None
+# The instance currently dispatching a function tool; lets meta-tools reach their
+# owner without the caller registering it globally.
+_executing_instance: contextvars.ContextVar[Matimo | None] = contextvars.ContextVar(
+    "matimo_executing_instance", default=None
+)
 
 
 def set_global_matimo_instance(instance: Matimo) -> None:
@@ -34,8 +40,11 @@ def set_global_matimo_instance(instance: Matimo) -> None:
 
 
 def get_global_matimo_instance() -> Matimo | None:
-    """Return the current global Matimo instance."""
-    return _global_instance
+    """
+    Return the Matimo instance in effect: the one executing the current function
+    tool if any, otherwise the instance registered via set_global_matimo_instance().
+    """
+    return _executing_instance.get() or _global_instance
 
 
 def tool(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:

{matimo_core-0.2.0 → matimo_core-0.4.0}/src/matimo/executors/function_executor.py

@@ -17,6 +17,7 @@ Example tool definition (definition.yaml):
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import importlib.util
 import inspect
 import logging
@@ -124,9 +125,11 @@ class FunctionExecutor:
             if inspect.iscoroutinefunction(run_fn):
                 result = await asyncio.wait_for(run_fn(*args), timeout=timeout_s)
             else:
-                # Run sync function in executor to avoid blocking the event loop
+                # Run sync function in executor to avoid blocking the event loop;
+                # copy_context keeps the executing-instance context var visible.
+                ctx = contextvars.copy_context()
                 result = await asyncio.wait_for(
-                    asyncio.get_running_loop().run_in_executor(None, run_fn, *args),
+                    asyncio.get_running_loop().run_in_executor(None, ctx.run, run_fn, *args),
                     timeout=timeout_s,
                 )
         except TimeoutError:

{matimo_core-0.2.0 → matimo_core-0.4.0}/src/matimo/executors/http_executor.py

@@ -17,6 +17,7 @@ from matimo.core.models import HttpExecution, ToolDefinition
 from matimo.encodings.parameter_encoding import apply_parameter_encodings
 from matimo.errors import ErrorCode, MatimoError, from_http_error
 from matimo.policy.content_validator import is_ssrf_target
+from matimo.policy.ssrf import ssrf_event_hooks
 
 logger = logging.getLogger("matimo")
 
@@ -142,7 +143,9 @@ class HttpExecutor:
         timeout_s = timeout_ms / 1000.0
 
         try:
-            async with httpx.AsyncClient(timeout=timeout_s) as client, client.stream(
+            async with httpx.AsyncClient(
+                timeout=timeout_s, event_hooks=ssrf_event_hooks()
+            ) as client, client.stream(
                 method=exec_cfg.method,
                 url=url,
                 headers=headers,

{matimo_core-0.2.0 → matimo_core-0.4.0}/src/matimo/instance.py

@@ -33,6 +33,7 @@ from matimo.approval.handler import (
     ApprovalRequest,
     definition_requires_approval,
     get_global_approval_handler,
+    requires_mandatory_human_approval,
 )
 from matimo.auth.injection import inject_auth_parameters
 from matimo.core.loader import ToolLoader
@@ -879,7 +880,15 @@ class Matimo:
         if exec_type == "function":
             # Function tools also get the caller's PolicyContext (e.g. so
             # matimo_approve_tool can check the approver's role and identity).
-            return await self._function_executor.execute(tool, params, credentials, context)
+            # The instance is also exposed to the tool so meta-tools such as
+            # matimo_list_skills see this instance without a global registration.
+            from matimo.decorators import _executing_instance
+
+            token = _executing_instance.set(self)
+            try:
+                return await self._function_executor.execute(tool, params, credentials, context)
+            finally:
+                _executing_instance.reset(token)
         raise MatimoError(
             f"Unknown execution type: '{exec_type}'",
             ErrorCode.EXECUTION_FAILED,
@@ -1036,12 +1045,15 @@ class Matimo:
         decides, and with no callback the call fails closed.
         """
         handler = self._approval_handler
-        if not handler.requires_approval(
+        # Some calls (execute with a shell) always need a human, whatever the YAML,
+        # the pre-approval settings or the caller's `approved` flag say.
+        mandatory_human = requires_mandatory_human_approval(tool.name, params)
+        if not mandatory_human and not handler.requires_approval(
             definition_requires_approval(tool, self.get_governance_mode()),
             _approval_scan_content(tool, params),
         ):
             return
-        if skip_prompt or handler.is_pre_approved(tool.name):
+        if (skip_prompt and not mandatory_human) or handler.is_pre_approved(tool.name, params):
             return
 
         agent_id = context.agent_id if context else None

{matimo_core-0.2.0 → matimo_core-0.4.0}/src/matimo/mcp/README.md

@@ -10,11 +10,8 @@ This module mirrors the TypeScript `@matimo/core/mcp` implementation and maintai
 - **Skill resources** - exposes Matimo skills as MCP resources (`skills://name`)
 - **HTTP transport** - Streamable HTTP with bearer-token auth, CORS, health endpoint
 - **Stdio transport** - stdio server for Claude Desktop integration
-- **mcp SDK 1.x/2.x compatibility** - mcp 2.0 replaced `Server`'s decorator-based
-  handler registration with constructor callables; `server.py` detects the
-  installed SDK's major version (`_mcp_major_version()`) and builds the server
-  via `_build_server_v1()` (decorators, mcp<2.0) or `_build_server_v2()`
-  (`on_list_tools=`/`on_call_tool=`/... constructor kwargs, mcp>=2.0)
+- **mcp SDK 2.x** - requires `mcp>=2.0`; `server.py` builds the `Server` with
+  `on_list_tools=`/`on_call_tool=`/... constructor callables (`_build_server()`)
 
 ---
 
@@ -180,31 +177,22 @@ embedding application provides a server-trusted approval signal.
 
 **Solution:** Register skills as MCP resources so clients can browse them like files:
 
-On mcp<2.0 this is registered post-construction via decorators
-(`_register_skill_resources_v1`); on mcp>=2.0 the same mapping is built as a
-pair of constructor callables instead (`_build_skill_resource_handlers_v2`),
-since `@server.list_resources()`/`@server.read_resource()` no longer exist.
+The mapping is built as a pair of `Server` constructor callables
+(`_build_skill_resource_handlers`), only when at least one skill exists:
 
 ```python
-def _register_skill_resources_v1(self, server: Any) -> None:
-    skills = self._matimo.list_skills()
-    
-    @server.list_resources()  # MCP: resources/list
-    async def handle_list_resources() -> list[Resource]:
-        return [
-            Resource(
-                uri=AnyUrl(f"skills://{s.name}"),
-                name=s.name,
-                description=s.description,
-                mimeType="text/markdown"
-            )
-            for s in skills
-        ]
-    
-    @server.read_resource()  # MCP: resources/read
-    async def handle_read_resource(uri: Any) -> str:
-        skill_name = str(uri).removeprefix("skills://")
-        return self._matimo.get_skill_content(skill_name)
+async def on_list_resources(ctx, params):  # MCP: resources/list
+    return ListResourcesResult(resources=[
+        Resource(uri=f"skills://{s.name}", name=s.name,
+                 description=s.description, mime_type="text/markdown")
+        for s in self._matimo.list_skills()
+    ])
+
+async def on_read_resource(ctx, params):  # MCP: resources/read
+    skill_name = str(params.uri).removeprefix("skills://")
+    content = self._matimo.get_skill_content(skill_name)
+    return ReadResourceResult(contents=[TextResourceContents(
+        uri=params.uri, mime_type="text/markdown", text=content)])
 ```
 
 **Result:**
@@ -286,13 +274,10 @@ async def _run_http(self, server: Any) -> None:
 2. await server.start()
    ├─ Suppress logging (clean stdout for JSON-RPC)
    ├─ Import MCP SDK
-   ├─ Create MCP Server instance
-   ├─ Register @server.list_tools() handler
-   ├─ Register @server.call_tool() handler
-   ├─ Register @server.list_resources() handler
-   ├─ Register @server.read_resource() handler
-   ├─ Load all tools: [slack_send_message, slack_post_reaction, ...]
-   ├─ Filter by allowlist/denylist: [slack_send_message, slack_post_reaction]
+   ├─ Build Server with on_list_tools / on_call_tool callables
+   ├─ Add on_list_resources / on_read_resource callables (only if skills exist)
+   ├─ Load all tools: [slack_send_channel_message, slack_add_reaction, ...]
+   ├─ Filter by allowlist/denylist: [slack_send_channel_message, slack_add_reaction]
    ├─ Extract auth placeholders: {SLACK_BOT_TOKEN}
    ├─ Resolve via SecretResolverChain: {SLACK_BOT_TOKEN: "xoxb-abc123"}
    ├─ Store in _resolved_secrets
@@ -306,7 +291,7 @@ async def _run_http(self, server: Any) -> None:
    ├─ Strips auth params from inputSchema
    ├─ Returns: [
    │   {
-   │     name: "slack_send_message",
+   │     name: "slack_send_channel_message",
    │     description: "Send a message to a Slack channel",
    │     inputSchema: {
    │       type: "object",
@@ -323,14 +308,14 @@ async def _run_http(self, server: Any) -> None:
    └─ Client receives tool list
       ↓
 5. Client calls: tools/call with {
-     name: "slack_send_message",
+     name: "slack_send_channel_message",
      arguments: {channel: "#general", text: "Hello"}
    }
-   ├─ Handler calls _call_tool("slack_send_message", {...})
+   ├─ Handler calls _call_tool("slack_send_channel_message", {...})
    ├─ Checks requires_approval (false for this tool)
    ├─ Gets pre-resolved credentials from _resolved_secrets
    ├─ Calls: matimo.execute(
-   │   "slack_send_message",
+   │   "slack_send_channel_message",
    │   {channel: "#general", text: "Hello"},
    │   credentials={SLACK_BOT_TOKEN: "xoxb-abc123"},
    │   approved=False
@@ -454,8 +439,8 @@ The `tools` and `exclude_tools` options support **Unix shell-style wildcard patt
 tools = [
     "slack_*",                    # All Slack tools
     "github_create_*",            # All GitHub create_* tools
-    "notion_database_*",          # All Notion database tools
-    "gmail_send",                 # Exact match (no wildcards)
+    "notion_*",                   # All Notion tools
+    "gmail-send-email",           # Exact match (no wildcards)
 ]
 
 # Exclude patterns
@@ -483,7 +468,7 @@ If a tool name matches both `tools` (allowlist) and `exclude_tools` (denylist),
 | Auth param filtering | ✅ `isAuthParameter()` | ✅ `_is_auth_parameter()` | Parity |
 | Approval via elicitation | ✅ `createElicitationApprovalCallback()` | ✅ `create_elicitation_approval_callback()` | Parity |
 | Pre-resolved secrets | ✅ `seedEnvironmentSecrets()` | ✅ `_seed_environment_secrets()` | Parity |
-| Skill resources | ✅ `registerSkillResources()` | ✅ `_register_skill_resources_v1()` / `_build_skill_resource_handlers_v2()` | Parity |
+| Skill resources | ✅ `registerSkillResources()` | ✅ `_build_skill_resource_handlers()` | Parity |
 | HTTP transport | ✅ `StreamableHTTPServerTransport` + sessions | ✅ `StreamableHTTPSessionManager` + stateless | Parity |
 | Stdio logging suppression | ✅ `logLevel: 'silent'` | ✅ `logging.setLevel(CRITICAL+1)` | Parity |
 | Test coverage | 95%+ | 95%+ | Parity |
@@ -540,9 +525,9 @@ uv run pytest packages/core/tests/unit/test_mcp_server.py -v
 **Solution:**
 
 ```bash
-pip install matimo[mcp]
+pip install "matimo[mcp]"
 # or
-pip install mcp>=1.0
+pip install "mcp>=2.0"
 ```
 
 ### Issue: "Auth token mismatch" in HTTP mode