vaultkit 0.1.0__tar.gz → 0.2.0__tar.gz

{vaultkit-0.1.0 → vaultkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.1.0
+Version: 0.2.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
 

{vaultkit-0.1.0 → vaultkit-0.2.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vaultkit"
-version = "0.1.0"
+version = "0.2.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.2.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.2.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.2.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.2.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.2.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.0 → vaultkit-0.2.0}/vaultkit/tools/definitions.py

@@ -63,13 +63,16 @@ def query_tool_def(
         }
 
     # Field guidance
-    fields_desc = "Columns to retrieve. Omit to return all accessible columns."
+    fields_desc = (
+        "Columns to retrieve. MUST be valid fields for the selected dataset. "
+        "Do NOT invent or guess field names. Only use fields listed below."
+    )
     if schema_hints:
-        examples = []
-        for ds, fields in list(schema_hints.items())[:2]:
-            examples.append(f"{ds}: [{', '.join(fields[:5])}]")
-        if examples:
-            fields_desc += f" Example fields — {'; '.join(examples)}."
+        field_rules = []
+        for ds, fields in list(schema_hints.items())[:5]:
+            field_rules.append(f"{ds}: {', '.join(fields)}")
+
+        fields_desc += "\n\nVALID FIELDS BY DATASET:\n" + "\n".join(field_rules)
 
     filter_condition = {
         "type": "object",

{vaultkit-0.1.0 → vaultkit-0.2.0}/vaultkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultkit
-Version: 0.1.0
+Version: 0.2.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
 

{vaultkit-0.1.0 → vaultkit-0.2.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.2.0/vaultkit.egg-info/entry_points.txt

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

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

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

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

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