vaultkit 0.1.1__tar.gz → 0.3.0__tar.gz

{vaultkit-0.1.1 → vaultkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.1.1
+Version: 0.3.0
 Summary: VaultKit Python SDK for policy-driven, runtime governed data access
 Author-email: VaultKit <founders@vaultkit.io>
 License: MIT
@@ -8,19 +8,21 @@ Project-URL: Homepage, https://github.com/vaultkit-inc/vaultkit-sdk-python
 Project-URL: Documentation, https://docs.vaultkit.io
 Project-URL: Source, https://github.com/vaultkit-inc/vaultkit-sdk-python
 Project-URL: Issues, https://github.com/vaultkit-inc/vaultkit-sdk-python/issues
-Keywords: ai,data,sdk,governance,security,agents,runtime
+Keywords: ai,data,sdk,governance,security,agents,runtime,mcp
 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.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.24.0
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == "mcp"
 
 # VaultKit Python SDK
 
@@ -72,6 +74,37 @@ print(result.rows)
 
 ---
 
+## Analytical Queries
+
+Aggregate, group, filter on aggregates and sort within a single dataset:
+
+```python
+result = client.execute(
+    dataset="orders",
+    fields=["region"],
+    aggregates=[{"func": "sum", "field": "amount", "alias": "total"}],
+    having=[{"field": "SUM(amount)", "operator": "gt", "value": 1000}],
+    order_by={"column": "total", "direction": "desc"},
+    limit=10,
+    purpose="Quarterly revenue by region",
+)
+# [{"region": "US", "total": 18250}, {"region": "CA", "total": 4100}, ...]
+```
+
+- `aggregates`: `func` is one of `count`, `sum`, `avg`, `min`, `max`; use `field="*"` with `count`.
+- `group_by`: optional. Defaults to `fields`; if given, it must include every entry in `fields`.
+- `having`: needs an aggregate expression such as `SUM(amount)`, not an alias.
+- `order_by`: a field, an aggregate alias or an aggregate expression, `asc` (default) or `desc`.
+- `fields` can be omitted for a single total, e.g. `aggregates=[{"func": "count", "field": "*"}]`.
+
+Policies apply to every field these clauses use. `min`/`max`/`sum`/`avg` over a masked
+field are denied; `count` is allowed. Joins are not supported.
+
+> Requires a VaultKit control plane with intent analytics support. Older control
+> planes ignore these parameters and return ungrouped rows.
+
+---
+
 ## AI Agent Usage
 
 VaultKit provides built-in tools for LLM agents.

{vaultkit-0.1.1 → vaultkit-0.3.0}/README.md

@@ -48,6 +48,37 @@ print(result.rows)
 
 ---
 
+## Analytical Queries
+
+Aggregate, group, filter on aggregates and sort within a single dataset:
+
+```python
+result = client.execute(
+    dataset="orders",
+    fields=["region"],
+    aggregates=[{"func": "sum", "field": "amount", "alias": "total"}],
+    having=[{"field": "SUM(amount)", "operator": "gt", "value": 1000}],
+    order_by={"column": "total", "direction": "desc"},
+    limit=10,
+    purpose="Quarterly revenue by region",
+)
+# [{"region": "US", "total": 18250}, {"region": "CA", "total": 4100}, ...]
+```
+
+- `aggregates`: `func` is one of `count`, `sum`, `avg`, `min`, `max`; use `field="*"` with `count`.
+- `group_by`: optional. Defaults to `fields`; if given, it must include every entry in `fields`.
+- `having`: needs an aggregate expression such as `SUM(amount)`, not an alias.
+- `order_by`: a field, an aggregate alias or an aggregate expression, `asc` (default) or `desc`.
+- `fields` can be omitted for a single total, e.g. `aggregates=[{"func": "count", "field": "*"}]`.
+
+Policies apply to every field these clauses use. `min`/`max`/`sum`/`avg` over a masked
+field are denied; `count` is allowed. Joins are not supported.
+
+> Requires a VaultKit control plane with intent analytics support. Older control
+> planes ignore these parameters and return ungrouped rows.
+
+---
+
 ## AI Agent Usage
 
 VaultKit provides built-in tools for LLM agents.

{vaultkit-0.1.1 → vaultkit-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vaultkit"
-version = "0.1.1"
+version = "0.3.0"
 description = "VaultKit Python SDK for policy-driven, runtime governed data access"
 authors = [
   { name = "VaultKit", email = "founders@vaultkit.io" }
 ]
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 license = { text = "MIT" }
 
 dependencies = [
@@ -25,6 +25,7 @@ keywords = [
   "security",
   "agents",
   "runtime",
+  "mcp",
 ]
 
 classifiers = [
@@ -32,13 +33,19 @@ classifiers = [
   "Intended Audience :: Developers",
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.8",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Software Development :: Libraries",
 ]
 
+[project.optional-dependencies]
+mcp = ["mcp>=1.27,<2"]
+
+[project.scripts]
+vaultkit-mcp = "vaultkit.mcp.__main__:main"
+
 [project.urls]
 Homepage = "https://github.com/vaultkit-inc/vaultkit-sdk-python"
 Documentation = "https://docs.vaultkit.io"

{vaultkit-0.1.1 → vaultkit-0.3.0}/vaultkit/__init__.py

@@ -53,7 +53,7 @@ from .models import (
 # Optional (nice DX improvement)
 from .tools import ToolBuilder, ToolExecutor
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "VaultKitClient",

{vaultkit-0.1.1 → vaultkit-0.3.0}/vaultkit/client.py

@@ -19,7 +19,11 @@ from vaultkit.models.query_result import QueryResult
 from vaultkit.utils.retry import RetryConfig, with_retries
 from vaultkit.utils.validation import (
     require_str,
+    validate_aggregates,
     validate_filters,
+    validate_group_by,
+    validate_having,
+    validate_order_by,
     validate_limit,
 )
 
@@ -98,6 +102,10 @@ class VaultKitClient:
         fields: Optional[List[str]] = None,
         filters: Optional[List[Dict[str, Any]]] = None,
         limit: Optional[int] = None,
+        aggregates: Optional[List[Dict[str, Any]]] = None,
+        group_by: Optional[List[str]] = None,
+        having: Optional[List[Dict[str, Any]]] = None,
+        order_by: Optional[Dict[str, Any]] = None,
         purpose: Optional[str] = None,
         requester_region: Optional[str] = None,
         requester_clearance: Optional[str] = None,
@@ -106,6 +114,18 @@ class VaultKitClient:
         """
         Submit an intent request and return data — full grant lifecycle internal.
 
+        Analytical queries (single dataset, no joins):
+            aggregates  [{"func": "sum", "field": "amount", "alias": "total"}]
+                        func is one of count, sum, avg, min, max; "*" only with count.
+            group_by    ["region"] — every field in `fields` must be listed when given.
+            having      [{"field": "SUM(amount)", "operator": "gt", "value": 1000}]
+                        field must be an aggregate expression, not an alias.
+            order_by    {"column": "total", "direction": "desc"}
+
+        `fields` may be omitted when `aggregates` is given (e.g. a single COUNT(*)).
+        Requires a control plane that supports intent analytics; older ones
+        ignore these parameters.
+
         Raises:
             DeniedError             Policy rejected. Do not retry.
             ApprovalRequiredError   Needs human approval (request_id attached).
@@ -126,6 +146,10 @@ class VaultKitClient:
             fields=fields,
             filters=filters,
             limit=limit,
+            aggregates=aggregates,
+            group_by=group_by,
+            having=having,
+            order_by=order_by,
             purpose=purpose,
             requester_region=requester_region,
             requester_clearance=requester_clearance,
@@ -214,6 +238,10 @@ class VaultKitClient:
         fields: Optional[List[str]] = None,
         filters: Optional[List[Dict[str, Any]]] = None,
         limit: Optional[int] = None,
+        aggregates: Optional[List[Dict[str, Any]]] = None,
+        group_by: Optional[List[str]] = None,
+        having: Optional[List[Dict[str, Any]]] = None,
+        order_by: Optional[Dict[str, Any]] = None,
         purpose: Optional[str] = None,
         requester_region: Optional[str] = None,
         requester_clearance: Optional[str] = None,
@@ -223,6 +251,10 @@ class VaultKitClient:
         dataset = require_str("dataset", dataset)
         limit = validate_limit(limit)
         filters = validate_filters(filters)
+        aggregates = validate_aggregates(aggregates)
+        group_by = validate_group_by(group_by)
+        having = validate_having(having)
+        order_by = validate_order_by(order_by)
 
         req: Dict[str, Any] = {"dataset": dataset}
         body: Dict[str, Any] = {"request": req}
@@ -235,6 +267,14 @@ class VaultKitClient:
             req["purpose"] = str(purpose)
         if filters is not None:
             req["filters"] = filters
+        if aggregates is not None:
+            req["aggregates"] = aggregates
+        if group_by is not None:
+            req["group_by"] = group_by
+        if having is not None:
+            req["having"] = having
+        if order_by is not None:
+            req["order_by"] = order_by
         if requester_region is not None:
             body["requester_region"] = requester_region
         if requester_clearance is not None:
@@ -248,6 +288,7 @@ class VaultKitClient:
                     "poll": poll,
                     "has_fields": fields is not None,
                     "has_filters": filters is not None,
+                    "has_aggregates": aggregates is not None,
                     "limit": limit,
                 },
             )

vaultkit-0.3.0/vaultkit/mcp/__init__.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+"""
+VaultKit MCP server (the ``[mcp]`` extra).
+
+This subpackage exposes VaultKit's governed tools over the Model Context
+Protocol so any MCP host (Claude Desktop, Cursor, custom agents) can query
+governed data.
+
+No policy evaluation happens here. This layer advertises tools by reusing
+``ToolBuilder`` and dispatches calls by reusing ``ToolExecutor``. Every policy
+decision, mask, grant and audit entry is performed by the control plane.
+
+Two deployments share one codebase:
+    - stdio  : one principal from environment variables (local use).
+    - http   : one principal per authenticated session (not yet implemented;
+               see identity.HttpClientResolver).
+
+The only difference between them is how the caller's identity is resolved into
+a VaultKitClient; everything else is shared.
+
+Install:
+    pip install vaultkit[mcp]
+
+Run:
+    vaultkit-mcp                 # stdio (default)
+    vaultkit-mcp --transport http --host 0.0.0.0 --port 8000   # not yet implemented
+"""
+
+from .server import McpServerConfig, build_server
+
+__all__ = ["McpServerConfig", "build_server"]

vaultkit-0.3.0/vaultkit/mcp/__main__.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+"""
+``vaultkit-mcp`` entrypoint.
+
+    vaultkit-mcp                                   # stdio (default), local use
+    vaultkit-mcp --transport http --port 8000      # hosted (not yet implemented)
+
+stdio is the local transport: an MCP host (Claude Desktop, Cursor, ...) launches
+this as a subprocess and pipes JSON-RPC over stdin/stdout. Credentials come from
+the environment (see StdioClientResolver).
+
+http (streamable HTTP) is the hosted transport. It is not wired up yet: it
+requires the per-principal OAuth exchange in HttpClientResolver first.
+"""
+
+import argparse
+import os
+import sys
+from typing import Optional
+
+from .identity import HttpClientResolver, StdioClientResolver
+from .server import McpServerConfig, build_server
+
+
+def _config_from_env() -> McpServerConfig:
+    def _flag(name: str, default: bool) -> bool:
+        raw = os.environ.get(name)
+        if raw is None:
+            return default
+        return raw.strip().lower() in ("1", "true", "yes", "on")
+
+    return McpServerConfig(
+        environment=os.environ.get("VAULTKIT_ENVIRONMENT", "production"),
+        include_discover=_flag("VAULTKIT_MCP_INCLUDE_DISCOVER", True),
+        include_query=_flag("VAULTKIT_MCP_INCLUDE_QUERY", True),
+        include_check_approval=_flag("VAULTKIT_MCP_INCLUDE_CHECK_APPROVAL", True),
+        fetch_schema_hints=_flag("VAULTKIT_MCP_SCHEMA_HINTS", True),
+        default_purpose=os.environ.get("VAULTKIT_MCP_DEFAULT_PURPOSE"),
+        default_requester_region=os.environ.get("VAULTKIT_MCP_DEFAULT_REGION"),
+    )
+
+
+async def _run_stdio(server) -> None:
+    from mcp.server.stdio import stdio_server
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+def _run_http(server, host: str, port: int) -> None:
+    # Not implemented. Streamable HTTP requires a session manager and an ASGI
+    # app, and — before that — the per-principal OAuth exchange in
+    # HttpClientResolver. Reference for the intended wiring:
+    #
+    #   from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+    #   import uvicorn
+    #   from starlette.applications import Starlette
+    #   ... mount the session manager, add OAuth token validation middleware,
+    #       then uvicorn.run(app, host=host, port=port)
+    raise NotImplementedError(
+        "Hosted HTTP transport is not implemented yet. Implement "
+        "HttpClientResolver (per-principal identity) first, then wire the "
+        "streamable-HTTP ASGI app here. Use --transport stdio for now."
+    )
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="vaultkit-mcp",
+        description="Expose VaultKit's governed tools over the Model Context Protocol.",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "http"),
+        default=os.environ.get("VAULTKIT_MCP_TRANSPORT", "stdio"),
+        help="Transport to serve on (default: stdio).",
+    )
+    parser.add_argument("--host", default=os.environ.get("VAULTKIT_MCP_HOST", "127.0.0.1"))
+    parser.add_argument("--port", type=int, default=int(os.environ.get("VAULTKIT_MCP_PORT", "8000")))
+    args = parser.parse_args(argv)
+
+    try:
+        import anyio
+    except ImportError:
+        print(
+            "The MCP extra is not installed. Install it with:\n"
+            "    pip install vaultkit[mcp]",
+            file=sys.stderr,
+        )
+        return 1
+
+    config = _config_from_env()
+
+    if args.transport == "stdio":
+        resolver = StdioClientResolver()
+        server = build_server(resolver, config)
+        try:
+            anyio.run(_run_stdio, server)
+        finally:
+            resolver.close()
+        return 0
+
+    # http
+    resolver = HttpClientResolver()
+    server = build_server(resolver, config)
+    _run_http(server, args.host, args.port)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vaultkit-0.3.0/vaultkit/mcp/identity.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+"""
+Identity resolution for the MCP server.
+
+A single interface, ``ClientResolver``, turns an incoming request into a
+``VaultKitClient``. This is the only part of the MCP layer that differs between
+deployments, which lets ``server.py`` be written once and run in either mode:
+
+    stdio  -> StdioClientResolver : one principal, read from env at startup.
+    http   -> HttpClientResolver  : one principal per authenticated request.
+
+The request handlers depend only on the ``ClientResolver`` interface and never
+know which implementation they received.
+"""
+
+import os
+from typing import Any, Optional
+
+from vaultkit.client import VaultKitClient
+
+
+class ClientResolver:
+    """Resolve an incoming request context into a VaultKitClient.
+
+    ``ctx`` is whatever the transport provides: ``None`` for stdio, or an
+    authenticated request context for http. Implementations use as much of it
+    as they need.
+    """
+
+    def resolve(self, ctx: Optional[Any] = None) -> VaultKitClient:  # pragma: no cover
+        raise NotImplementedError
+
+    def close(self) -> None:  # pragma: no cover
+        pass
+
+
+class StdioClientResolver(ClientResolver):
+    """Single-principal resolver for local (stdio) use.
+
+    Reads credentials from the environment once and returns the same client for
+    every call. Over stdio there is a single caller (the host process that
+    launched the server), so there is a single principal, and ``ctx`` is
+    ignored.
+
+    Required environment variables:
+        VAULTKIT_BASE_URL
+        VAULTKIT_TOKEN
+        VAULTKIT_ORG
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+        org: Optional[str] = None,
+    ) -> None:
+        self._base_url = base_url or os.environ.get("VAULTKIT_BASE_URL")
+        self._token = token or os.environ.get("VAULTKIT_TOKEN")
+        self._org = org or os.environ.get("VAULTKIT_ORG")
+
+        missing = [
+            name
+            for name, val in (
+                ("VAULTKIT_BASE_URL", self._base_url),
+                ("VAULTKIT_TOKEN", self._token),
+                ("VAULTKIT_ORG", self._org),
+            )
+            if not val
+        ]
+        if missing:
+            raise RuntimeError(
+                "Missing required VaultKit credentials for the MCP server: "
+                + ", ".join(missing)
+                + ". Set them in the environment (or your MCP host's server "
+                "config 'env' block) before starting vaultkit-mcp."
+            )
+
+        self._client: Optional[VaultKitClient] = None
+
+    def resolve(self, ctx: Optional[Any] = None) -> VaultKitClient:
+        if self._client is None:
+            self._client = VaultKitClient(
+                base_url=self._base_url,  # type: ignore[arg-type]
+                token=self._token,  # type: ignore[arg-type]
+                org=self._org,  # type: ignore[arg-type]
+            )
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+
+class HttpClientResolver(ClientResolver):
+    """Per-principal resolver for hosted (streamable-HTTP) use.
+
+    Not yet implemented. Over http each request may belong to a different
+    principal, so a client cannot be built once at startup; it must be resolved
+    per request from the authenticated identity.
+
+    Intended implementation:
+        1. Read the bearer token from ``ctx`` (the request's auth context).
+        2. Resolve it to a (token, org) principal, delegating to the control
+           plane rather than trusting client-supplied claims.
+        3. Construct and return a VaultKitClient for that principal.
+        4. Optionally cache clients per principal and close idle ones.
+    """
+
+    def resolve(self, ctx: Optional[Any] = None) -> VaultKitClient:
+        raise NotImplementedError(
+            "Hosted HTTP identity resolution is not implemented yet. "
+            "Run the server with --transport stdio, or implement "
+            "HttpClientResolver.resolve to exchange the request's OAuth token "
+            "for a VaultKit principal via the control plane."
+        )

vaultkit-0.3.0/vaultkit/mcp/server.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+"""
+The VaultKit MCP server.
+
+Two handlers, both thin:
+
+    list_tools  -> reuse ToolBuilder to advertise the caller's authorized tools.
+    call_tool   -> reuse ToolExecutor to run a call and return its result.
+
+This uses the low-level ``mcp.server.lowlevel.Server`` rather than the
+``@mcp.tool`` decorator API because the decorator registers a static tool list
+at startup, whereas VaultKit's tool list is per-principal: different callers are
+authorized for different datasets. ``list_tools`` therefore has to be computed
+per session, which the low-level API allows.
+
+The VaultKit SDK is synchronous (blocking HTTP and polling), while MCP handlers
+are async. Blocking work is offloaded to a worker thread via
+``anyio.to_thread.run_sync`` so it does not stall the event loop. This is
+required once multiple callers can be served concurrently, and harmless for the
+single-caller stdio case.
+"""
+
+import json
+from dataclasses import dataclass
+from typing import List, Optional
+
+import anyio
+import mcp.types as types
+from mcp.server.lowlevel import Server
+
+from vaultkit.tools.adapters import ToolProvider
+from vaultkit.tools.adapters.mcp import to_mcp_tool
+from vaultkit.tools.builder import ToolBuilder
+from vaultkit.tools.executor import ToolExecutor
+
+from .identity import ClientResolver
+
+
+@dataclass
+class McpServerConfig:
+    """Server-wide configuration (not per-call; per-call args come from the agent)."""
+
+    environment: str = "production"
+    include_discover: bool = True
+    include_query: bool = True
+    # check_approval is exposed by default: the approval flow is asynchronous,
+    # so the agent needs a way to poll a pending request to completion.
+    include_check_approval: bool = True
+    # Schema hints feed the agent the exact valid field names per dataset, which
+    # guards against field-name hallucination. Keep on unless a very large
+    # catalog makes startup slow.
+    fetch_schema_hints: bool = True
+    # Optional fallbacks if an agent omits them (agents normally supply purpose).
+    default_purpose: Optional[str] = None
+    default_requester_region: Optional[str] = None
+    server_name: str = "vaultkit"
+
+
+def build_server(resolver: ClientResolver, config: Optional[McpServerConfig] = None) -> Server:
+    """Wire a low-level MCP Server around the given identity resolver.
+
+    Args:
+        resolver: Turns a request context into a VaultKitClient, and thereby
+            determines whether this is a single-principal (stdio) or
+            per-principal (http) server.
+        config: Server-wide options. Defaults are suitable for local (stdio) use.
+
+    Returns:
+        A configured ``mcp.server.lowlevel.Server`` ready to run over any
+        transport.
+    """
+    cfg = config or McpServerConfig()
+    server: Server = Server(cfg.server_name)
+
+    @server.list_tools()
+    async def _list_tools() -> List[types.Tool]:
+        # Resolve the caller -> client, then build their authorized tool list.
+        # RAW gives canonical defs; those are mapped to MCP Tools by to_mcp_tool.
+        client = resolver.resolve(_current_ctx(server))
+
+        def _build():
+            builder = ToolBuilder(client)
+            return builder.build(
+                provider=ToolProvider.RAW,
+                environment=cfg.environment,
+                include_discover=cfg.include_discover,
+                include_query=cfg.include_query,
+                include_check_approval=cfg.include_check_approval,
+                fetch_schema_hints=cfg.fetch_schema_hints,
+            )
+
+        canonical = await anyio.to_thread.run_sync(_build)
+        return [to_mcp_tool(t) for t in canonical]
+
+    @server.call_tool()
+    async def _call_tool(name: str, arguments: dict) -> List[types.ContentBlock]:
+        # Resolve the caller -> client, then dispatch through the executor.
+        # The executor never raises: denials, pending-approval and masking all
+        # come back as a structured dict with a `status` field, which is
+        # forwarded verbatim. A policy denial is a valid governed answer, not a
+        # protocol error, so it is not raised or marked isError.
+        client = resolver.resolve(_current_ctx(server))
+
+        def _run():
+            executor = ToolExecutor(
+                client,
+                default_purpose=cfg.default_purpose,
+                default_requester_region=cfg.default_requester_region,
+            )
+            return executor.execute(name, arguments or {})
+
+        result = await anyio.to_thread.run_sync(_run)
+        text = json.dumps(result, default=str, ensure_ascii=False, indent=2)
+        return [types.TextContent(type="text", text=text)]
+
+    return server
+
+
+def _current_ctx(server: Server):
+    """Return the active request context, or None if there is none.
+
+    stdio resolvers ignore this. The http resolver uses it to reach the
+    authenticated identity. Accessing ``request_context`` outside a request
+    raises, so it is guarded to keep the single-principal case working.
+    """
+    try:
+        return server.request_context
+    except Exception:
+        return None

vaultkit-0.3.0/vaultkit/tools/adapters/mcp.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+"""
+MCP tool adapter.
+
+Converts a canonical VaultKit tool definition into an ``mcp.types.Tool``,
+exactly the way ``to_anthropic_tool`` and ``to_openai_tool`` convert into
+their provider shapes.
+
+Canonical shape (from vaultkit.tools.definitions):
+    {"name": str, "description": str, "input_schema": {...}}
+
+MCP shape (mcp.types.Tool):
+    Tool(name=..., description=..., inputSchema={...})
+
+The only real work is the ``input_schema`` -> ``inputSchema`` rename and
+wrapping the dict in the MCP type. No governance logic lives here — this is
+pure translation, the same as every other adapter in this package.
+"""
+
+from typing import Any, Dict
+
+import mcp.types as types
+
+
+def to_mcp_tool(canonical: Dict[str, Any]) -> types.Tool:
+    """Convert one canonical tool def into an MCP Tool.
+
+    Args:
+        canonical: A dict with ``name``, ``description`` and ``input_schema``,
+            as produced by ``vaultkit.tools.definitions``.
+
+    Returns:
+        An ``mcp.types.Tool`` suitable for returning from a ``list_tools``
+        handler.
+    """
+    return types.Tool(
+        name=canonical["name"],
+        description=canonical.get("description"),
+        inputSchema=canonical["input_schema"],
+    )

{vaultkit-0.1.1 → vaultkit-0.3.0}/vaultkit/tools/definitions.py

@@ -115,6 +115,8 @@ def query_tool_def(
         "description": (
             "Query a governed dataset through VaultKit. Policies are enforced automatically: "
             "sensitive fields may be masked and some datasets require approval before data is returned. "
+            "Supports aggregation (count/sum/avg/min/max), grouping, having and sorting on a single dataset; "
+            "joins are not supported. "
             "Returns data or a pending status if approval is required."
         ),
         "input_schema": {
@@ -143,6 +145,71 @@ def query_tool_def(
                     "maximum": 10000,
                     "description": "Maximum number of rows to return.",
                 },
+                "aggregates": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "func": {"type": "string", "enum": ["count", "sum", "avg", "min", "max"]},
+                            "field": {
+                                "type": "string",
+                                "description": "A field of the selected dataset, or '*' with count.",
+                            },
+                            "alias": {
+                                "type": "string",
+                                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+                                "description": "Name of the result column. Use it in order_by.",
+                            },
+                        },
+                        "required": ["func", "field"],
+                    },
+                    "description": (
+                        "Aggregate functions over the selected dataset. When aggregating, every entry in "
+                        "'fields' is a grouping column. 'fields' may be omitted for a single total.\n\n"
+                        "Example: [{func: 'sum', field: 'amount', alias: 'total'}]\n"
+                        "min/max/sum/avg over masked fields are denied by policy; count is allowed."
+                    ),
+                },
+                "group_by": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Fields to group by. Optional: defaults to 'fields'. If given, it must include "
+                        "every entry in 'fields'."
+                    ),
+                },
+                "having": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "field": {
+                                "type": "string",
+                                "description": "An aggregate expression such as 'SUM(amount)'. Aliases are not allowed here.",
+                            },
+                            "operator": {"type": "string", "enum": ["gt", "lt", "eq", "gte", "lte"]},
+                            "value": {"type": "number"},
+                        },
+                        "required": ["field", "operator", "value"],
+                    },
+                    "description": (
+                        "Filters applied after aggregation. Requires 'aggregates'.\n\n"
+                        "Example: [{field: 'SUM(amount)', operator: 'gt', value: 1000}]"
+                    ),
+                },
+                "order_by": {
+                    "type": "object",
+                    "properties": {
+                        "column": {
+                            "type": "string",
+                            "description": "A field, an aggregate alias, or an aggregate expression.",
+                        },
+                        "direction": {"type": "string", "enum": ["asc", "desc"], "default": "asc"},
+                    },
+                    "required": ["column"],
+                    "description": "Sort order of the results.",
+                },
                 "purpose": {
                     "type": "string",
                     "description": (

{vaultkit-0.1.1 → vaultkit-0.3.0}/vaultkit/tools/executor.py

@@ -105,6 +105,10 @@ class ToolExecutor:
             fields=args.get("fields"),
             filters=args.get("filters"),
             limit=args.get("limit"),
+            aggregates=args.get("aggregates"),
+            group_by=args.get("group_by"),
+            having=args.get("having"),
+            order_by=args.get("order_by"),
             purpose=purpose,
             requester_region=args.get("requester_region") or self._default_requester_region,
         )

{vaultkit-0.1.1 → vaultkit-0.3.0}/vaultkit/utils/validation.py

@@ -85,3 +85,77 @@ def validate_filters(value: Optional[Any]) -> Optional[list]:
             )
 
     return value
+
+
+# Analytical clauses. Only the shape is checked here; the control plane
+# validates functions, fields and operators and returns a clear error.
+
+def _require_list_of_dicts(name: str, value: Optional[Any]) -> Optional[list]:
+    if value is None:
+        return None
+
+    if not isinstance(value, list):
+        raise ValidationError(
+            f"{name} must be a list",
+            context=ErrorContext(raw=value),
+        )
+
+    for item in value:
+        if not isinstance(item, dict):
+            raise ValidationError(
+                f"each {name} entry must be an object",
+                context=ErrorContext(raw=item),
+            )
+
+    return value
+
+
+def validate_aggregates(value: Optional[Any]) -> Optional[list]:
+    value = _require_list_of_dicts("aggregates", value)
+    if value is None:
+        return None
+
+    if not value:
+        raise ValidationError(
+            "aggregates cannot be empty",
+            context=ErrorContext(raw=value),
+        )
+
+    for agg in value:
+        if not agg.get("func") or not agg.get("field"):
+            raise ValidationError(
+                "each aggregate needs 'func' and 'field'",
+                context=ErrorContext(raw=agg),
+            )
+
+    return value
+
+
+def validate_group_by(value: Optional[Any]) -> Optional[list]:
+    if value is None:
+        return None
+
+    if not isinstance(value, list) or not all(isinstance(v, str) and v.strip() for v in value):
+        raise ValidationError(
+            "group_by must be a list of field names",
+            context=ErrorContext(raw=value),
+        )
+
+    return value
+
+
+def validate_having(value: Optional[Any]) -> Optional[list]:
+    return _require_list_of_dicts("having", value)
+
+
+def validate_order_by(value: Optional[Any]) -> Optional[Dict[str, Any]]:
+    if value is None:
+        return None
+
+    if not isinstance(value, dict) or not value.get("column"):
+        raise ValidationError(
+            "order_by must be an object with a 'column'",
+            context=ErrorContext(raw=value),
+        )
+
+    return value

{vaultkit-0.1.1 → vaultkit-0.3.0}/vaultkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.1.1
+Version: 0.3.0
 Summary: VaultKit Python SDK for policy-driven, runtime governed data access
 Author-email: VaultKit <founders@vaultkit.io>
 License: MIT
@@ -8,19 +8,21 @@ Project-URL: Homepage, https://github.com/vaultkit-inc/vaultkit-sdk-python
 Project-URL: Documentation, https://docs.vaultkit.io
 Project-URL: Source, https://github.com/vaultkit-inc/vaultkit-sdk-python
 Project-URL: Issues, https://github.com/vaultkit-inc/vaultkit-sdk-python/issues
-Keywords: ai,data,sdk,governance,security,agents,runtime
+Keywords: ai,data,sdk,governance,security,agents,runtime,mcp
 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.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.24.0
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == "mcp"
 
 # VaultKit Python SDK
 
@@ -72,6 +74,37 @@ print(result.rows)
 
 ---
 
+## Analytical Queries
+
+Aggregate, group, filter on aggregates and sort within a single dataset:
+
+```python
+result = client.execute(
+    dataset="orders",
+    fields=["region"],
+    aggregates=[{"func": "sum", "field": "amount", "alias": "total"}],
+    having=[{"field": "SUM(amount)", "operator": "gt", "value": 1000}],
+    order_by={"column": "total", "direction": "desc"},
+    limit=10,
+    purpose="Quarterly revenue by region",
+)
+# [{"region": "US", "total": 18250}, {"region": "CA", "total": 4100}, ...]
+```
+
+- `aggregates`: `func` is one of `count`, `sum`, `avg`, `min`, `max`; use `field="*"` with `count`.
+- `group_by`: optional. Defaults to `fields`; if given, it must include every entry in `fields`.
+- `having`: needs an aggregate expression such as `SUM(amount)`, not an alias.
+- `order_by`: a field, an aggregate alias or an aggregate expression, `asc` (default) or `desc`.
+- `fields` can be omitted for a single total, e.g. `aggregates=[{"func": "count", "field": "*"}]`.
+
+Policies apply to every field these clauses use. `min`/`max`/`sum`/`avg` over a masked
+field are denied; `count` is allowed. Joins are not supported.
+
+> Requires a VaultKit control plane with intent analytics support. Older control
+> planes ignore these parameters and return ungrouped rows.
+
+---
+
 ## AI Agent Usage
 
 VaultKit provides built-in tools for LLM agents.

{vaultkit-0.1.1 → vaultkit-0.3.0}/vaultkit.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ vaultkit/client.py
 vaultkit.egg-info/PKG-INFO
 vaultkit.egg-info/SOURCES.txt
 vaultkit.egg-info/dependency_links.txt
+vaultkit.egg-info/entry_points.txt
 vaultkit.egg-info/requires.txt
 vaultkit.egg-info/top_level.txt
 vaultkit/core/__init__.py
@@ -15,6 +16,10 @@ vaultkit/core/polling.py
 vaultkit/errors/__init__.py
 vaultkit/errors/base.py
 vaultkit/errors/exceptions.py
+vaultkit/mcp/__init__.py
+vaultkit/mcp/__main__.py
+vaultkit/mcp/identity.py
+vaultkit/mcp/server.py
 vaultkit/models/__init__.py
 vaultkit/models/dataset_info.py
 vaultkit/models/dataset_schema.py
@@ -27,6 +32,7 @@ vaultkit/tools/executor.py
 vaultkit/tools/schemas.py
 vaultkit/tools/adapters/__init__.py
 vaultkit/tools/adapters/anthropic.py
+vaultkit/tools/adapters/mcp.py
 vaultkit/tools/adapters/openai.py
 vaultkit/utils/__init__.py
 vaultkit/utils/retry.py

vaultkit-0.3.0/vaultkit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vaultkit-mcp = vaultkit.mcp.__main__:main

vaultkit-0.3.0/vaultkit.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.24.0
+
+[mcp]
+mcp<2,>=1.27

vaultkit-0.1.1/vaultkit.egg-info/requires.txt

@@ -1 +0,0 @@
-httpx>=0.24.0