connectkit 0.1.0__py3-none-any.whl

connectkit/__init__.py

@@ -0,0 +1,26 @@
+"""ConnectKit — connect AI agents to SaaS accounts.
+
+One YAML file per service. OAuth, token vault, and tool discovery handled automatically.
+"""
+
+__version__ = "0.1.0"
+
+from connectkit.bridge import ConnectKitBridge
+from connectkit.meta_tools import TOOL_SPECS
+from connectkit.sdk_adapter import ToolSpec
+from connectkit.spec import AuthType, ConnectorSpec, RequiredField, ToolSourceType, CLIToolSource
+from connectkit.utils import ensure_cli_installed
+from connectkit.vault import CredentialVault
+
+__all__ = [
+    "ConnectorSpec",
+    "AuthType",
+    "ToolSourceType",
+    "RequiredField",
+    "CredentialVault",
+    "ConnectKitBridge",
+    "ToolSpec",
+    "TOOL_SPECS",
+    "CLIToolSource",
+    "ensure_cli_installed",
+]

connectkit/backends/cli.py

@@ -0,0 +1,220 @@
+"""CLIAdapter — user-aware subprocess wrapper for CLI-based connectors.
+
+Unlike the old CLIToolAdapter singleton in EA's SDK, this:
+1.  Reads per-user tokens from CredentialVault
+2.  Sets env vars per invocation (no global state)
+3.  Discovers tools by parsing CLI --help or a known tool list
+4.  Returns namespaced ToolDefinition objects
+
+Usage:
+    adapter = CLIAdapter(spec, vault, user_id="alice")
+    if not adapter.is_available():
+        print(f"CLI not installed: {adapter._source.install}")
+
+    tools = adapter.discover_tools(namespace="google-workspace")
+"""
+
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess
+from typing import Any
+
+from connectkit.spec import CLIToolSource, ConnectorSpec, ToolDescription
+from connectkit.vault import CredentialVault
+
+logger = logging.getLogger("connectkit")
+
+
+class CLIAdapter:
+    """Wraps a CLI tool with per-user token injection.
+
+    Each tool is a closure that spans a subprocess with the user's
+    OAuth token in the environment.
+    """
+
+    def __init__(
+        self,
+        spec: ConnectorSpec,
+        vault: CredentialVault,
+        user_id: str,
+        timeout: int = 60,
+    ):
+        self.spec = spec
+        self.vault = vault
+        self.user_id = user_id
+        self.timeout = timeout
+        self._source: CLIToolSource = spec.tool_source  # type: ignore[assignment]
+        self._command = self._source.command
+
+    def is_available(self) -> bool:
+        return shutil.which(self._command) is not None
+
+    def _build_env(self) -> dict[str, str]:
+        env = os.environ.copy()
+        token_data = self.vault.get_token(self.spec.name)
+        if not token_data:
+            return env
+
+        for cred_key, env_var in self._source.env_mapping.items():
+            if cred_key == "access_token":
+                env[env_var] = token_data.get("access_token", "")
+            elif cred_key == "api_key":
+                env[env_var] = token_data.get("api_key", "")
+            elif cred_key in token_data:
+                env[env_var] = str(token_data[cred_key])
+
+        return env
+
+    def run(self, args: list[str]) -> tuple[int, str, str]:
+        env = self._build_env()
+        cmd = [self._command] + args
+        try:
+            result = subprocess.run(
+                cmd,
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+            )
+            return result.returncode, result.stdout.strip(), result.stderr.strip()
+        except subprocess.TimeoutExpired:
+            return -2, "", f"Command timed out after {self.timeout}s: {' '.join(cmd)}"
+        except FileNotFoundError:
+            return -1, "", f"Command not found: {self._command}. Install: {self._source.install}"
+        except Exception as e:
+            return -3, "", f"Subprocess error: {e}"
+
+    def list_commands(self) -> list[str]:
+        rc, stdout, _ = self.run(["--list-commands"])
+        if rc == 0:
+            try:
+                return json.loads(stdout)
+            except json.JSONDecodeError:
+                return [line.strip() for line in stdout.split("\n") if line.strip()]
+
+        rc, stdout, _ = self.run(["--help"])
+        if rc == 0:
+            return _parse_subcommands_from_help(stdout)
+
+        return []
+
+    def discover_tools(self, namespace: str) -> list[Any]:
+        commands = self.list_commands()
+        descriptions_by_name = {
+            td.name: td for td in self.spec.tool_descriptions
+        }
+
+        tools = []
+        for cmd in commands:
+            safe_name = cmd.replace(" ", "_").replace("-", "_").replace(":", "_")
+            tool_name = f"{namespace}__{safe_name}"
+
+            td = descriptions_by_name.get(tool_name)
+            description = (
+                td.description if td
+                else f"{self.spec.display}: {cmd}"
+            )
+
+            parameter_descriptions = td.parameter_descriptions if td else {}
+
+            tool_def = _build_connector_tool(
+                name=tool_name,
+                description=description,
+                adapter=self,
+                args=args_from_command(cmd),
+                parameter_descriptions=parameter_descriptions,
+            )
+            tools.append(tool_def)
+
+        return tools
+
+
+def args_from_command(cmd: str) -> list[str]:
+    """Convert a command string like 'gmail:messages:list' to CLI args."""
+    return cmd.replace(":", " ").split()
+
+
+def _parse_subcommands_from_help(help_text: str) -> list[str]:
+    commands = []
+    for line in help_text.split("\n"):
+        if not line.strip():
+            continue
+        match = re.search(r"\s{2,}([a-z][a-z0-9_:-]+)(?:\s|$)", line)
+        if match:
+            commands.append(match.group(1))
+    return commands
+
+
+def _build_connector_tool(
+    name: str,
+    description: str,
+    adapter: CLIAdapter,
+    args: list[str],
+    parameter_descriptions: dict[str, str] | None = None,
+) -> Any:
+    """Build a ToolDefinition-compatible object for a connector tool.
+
+    Uses a closure that wraps the subprocess call. The closure:
+    1.  Formats kwargs as --key value pairs
+    2.  Calls adapter.run(args + extra_args)
+    3.  Parses stdout as JSON if possible
+    4.  Returns a dict with content, structured_content, and error flag
+    """
+
+    def _sync_invoke(**kwargs: Any) -> dict:
+        extra = []
+        for key, val in kwargs.items():
+            if val is None:
+                continue
+            extra.extend([f"--{key.replace('_', '-')}", str(val)])
+
+        rc, stdout, stderr = adapter.run(args + extra)
+
+        result: dict[str, Any] = {
+            "content": "",
+            "structured_content": None,
+            "is_error": False,
+        }
+
+        if rc != 0:
+            result["content"] = f"Error (code {rc}): {stderr or stdout}"
+            result["is_error"] = True
+            return result
+
+        try:
+            parsed = json.loads(stdout)
+            result["content"] = stdout[:4000]
+            result["structured_content"] = parsed
+            return result
+        except (json.JSONDecodeError, ValueError):
+            result["content"] = stdout[:4000]
+            return result
+
+    async def _async_invoke(**kwargs: Any) -> dict:
+        import asyncio
+        return await asyncio.to_thread(_sync_invoke, **kwargs)
+
+    params: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            k: {"type": "string", "description": v}
+            for k, v in (parameter_descriptions or {}).items()
+        },
+    }
+
+    return {
+        "name": name,
+        "description": description,
+        "parameters": params,
+        "function": _sync_invoke,
+        "ainvoke": _async_invoke,
+        "annotations": {
+            "read_only": False,
+            "destructive": True,
+            "idempotent": False,
+            "title": name,
+        },
+    }

connectkit/backends/mcp.py

@@ -0,0 +1,87 @@
+"""MCPAdapter — vault token injection for MCP tool source connectors.
+
+This adapter wraps a ConnectorSpec whose tool_source.type is "mcp".
+It reads the user's OAuth/API token from CredentialVault, injects it
+into the MCP server process environment, then returns tool definitions.
+
+For EA integration, the actual MCP server lifecycle is managed by the
+existing MCPToolBridge + MCPManager. This adapter just provides the
+env dict with per-user tokens.
+
+Usage:
+    adapter = MCPAdapter(spec, vault, user_id="alice")
+    server_env = adapter.build_server_env()
+    # Pass server_env to MCPToolBridge when registering the server
+"""
+
+import logging
+from typing import Any
+
+from connectkit.spec import ConnectorSpec, MCPToolSource
+from connectkit.vault import CredentialVault
+
+logger = logging.getLogger("connectkit")
+
+
+class MCPAdapter:
+    """Wraps an MCP server connector with per-user token injection."""
+
+    def __init__(
+        self,
+        spec: ConnectorSpec,
+        vault: CredentialVault,
+        user_id: str,
+    ):
+        self.spec = spec
+        self.vault = vault
+        self.user_id = user_id
+        self._source: MCPToolSource = spec.tool_source  # type: ignore[assignment]
+
+    @property
+    def server_name(self) -> str:
+        return self._source.server_name
+
+    @property
+    def command(self) -> str:
+        return self._source.command
+
+    def build_server_env(self) -> dict[str, str]:
+        import os
+
+        env = os.environ.copy()
+        token_data = self.vault.get_token(self.spec.name)
+        if not token_data:
+            return env
+
+        for cred_key, env_var in self._source.env_mapping.items():
+            if cred_key == "access_token":
+                env[env_var] = token_data.get("access_token", "")
+            elif cred_key == "api_key":
+                env[env_var] = token_data.get("api_key", "")
+            elif cred_key in token_data:
+                env[env_var] = str(token_data[cred_key])
+
+        return env
+
+    def get_mcp_config(self) -> dict[str, Any]:
+        """Return config dict suitable for registering with MCPManager.
+
+        The caller can pass this to their existing MCP server registry.
+        """
+        return {
+            "command": self._source.command,
+            "env": self.build_server_env(),
+            "transport": "stdio",
+        }
+
+    def health(self) -> dict[str, Any]:
+        try:
+            token_data = self.vault.get_token(self.spec.name)
+            has_token = token_data is not None and "access_token" in token_data
+            return {
+                "status": "ok" if has_token else "not_connected",
+                "service": self.spec.name,
+                "server": self._source.server_name,
+            }
+        except Exception as e:
+            return {"status": "error", "service": self.spec.name, "error": str(e)}

connectkit/bridge.py

@@ -0,0 +1,116 @@
+"""ConnectKitBridge — EA integration point.
+
+Mirrors the MCPToolBridge pattern:
+    bridge = ConnectKitBridge(user_id="alice")
+    await bridge.discover()
+    tools = bridge.get_tool_definitions()
+
+EA's runner.py injects this between native_tools and AgentLoop creation.
+Each tool dict contains: name, description, parameters, function, ainvoke,
+annotations, and optional _is_mcp_placeholder.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from connectkit.runtime import ConnectorRuntime
+from connectkit.spec import ConnectorSpec
+from connectkit.vault import CredentialVault
+
+logger = logging.getLogger("connectkit")
+
+
+def _default_vault_path(user_id: str) -> str:
+    return str(Path("data") / "users" / user_id / "connectkit")
+
+
+def _default_spec_dir() -> str:
+    import os
+
+    env = os.environ.get("CONNECTKIT_SPEC_DIR")
+    if env:
+        return env
+
+    try:
+        import importlib.resources
+
+        packaged = Path(str(importlib.resources.files("connectkit") / "connectors"))
+        if packaged.exists():
+            return str(packaged)
+    except Exception:
+        pass
+
+    return str(Path(__file__).parent.parent / "connectors")
+
+
+def get_vault(user_id: str, vault_path: str | None = None) -> CredentialVault:
+    """Get or create a CredentialVault for a user."""
+    path = vault_path or _default_vault_path(user_id)
+    return CredentialVault(path)
+
+
+class ConnectKitBridge:
+    """Bridge between Agent Connect and an agent loop.
+
+    Mirrors the MCPToolBridge pattern exactly:
+        - discover() → loads connector specs, checks vault, discovers tools
+        - get_tool_definitions() → returns list[dict]
+        - health() → reports connector health
+        - list_available() → catalog of known connectors
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        spec_dir: str | None = None,
+        vault_path: str | None = None,
+    ):
+        self.user_id = user_id
+        self._spec_dir = spec_dir or _default_spec_dir()
+        self._vault = get_vault(user_id, vault_path)
+        self._runtime = ConnectorRuntime(self._spec_dir, self._vault, user_id)
+        self._tools: list[dict[str, Any]] = []
+
+    @property
+    def spec_dir(self) -> str:
+        return self._spec_dir
+
+    @property
+    def runtime(self) -> ConnectorRuntime:
+        return self._runtime
+
+    @property
+    def vault(self) -> CredentialVault:
+        return self._vault
+
+    async def discover(self) -> None:
+        self._tools = self._runtime.get_tools()
+        logger.info(
+            f"connectkit.discover user={self.user_id} tools={len(self._tools)}"
+        )
+
+    def get_tool_definitions(self) -> list[dict[str, Any]]:
+        return self._tools
+
+    def list_available(self) -> list[dict[str, Any]]:
+        return self._runtime.list_available()
+
+    def list_available_specs(self) -> list[ConnectorSpec]:
+        """Return full ConnectorSpec objects for all known connectors."""
+        return self._runtime.get_specs()
+
+    def health(self) -> dict[str, Any]:
+        vault_health = self._vault.health()
+        connector_health = self._runtime.health()
+        return {
+            "vault": vault_health,
+            "connectors": connector_health,
+            "total_tools": len(self._tools),
+        }
+
+    def connected_services(self) -> list[str]:
+        return self._vault.list_connected()
+
+    def reload_specs(self) -> None:
+        self._runtime.reload()

connectkit/connectors/accelo.yaml

@@ -0,0 +1,26 @@
+name: accelo
+display: Accelo
+icon: accelo
+category: invoicing
+version: '1.0'
+description: Accelo
+auth:
+  type: oauth2
+  oauth2:
+    authorize_url: https://${connectionConfig.subdomain}.api.accelo.com/oauth2/v0/authorize
+    token_url: https://${connectionConfig.subdomain}.api.accelo.com/oauth2/v0/token
+    scopes:
+    - read
+    token_env_var: ACCELO_ACCESS_TOKEN
+  required_fields:
+  - name: subdomain
+    label: Accelo Domain
+    placeholder: domain
+    input_type: text
+    help_text: The subdomain of your Accelo account
+    optional: false
+setup_guide_url: https://nango.dev/docs/api-integrations/accelo/how-to-register-your-own-accelo-api-oauth-app
+tool_source:
+  type: mcp
+  server_name: accelo
+  command: accelo-mcp-server

connectkit/connectors/active-campaign.yaml

@@ -0,0 +1,28 @@
+name: active-campaign
+display: ActiveCampaign
+icon: active
+category: marketing
+version: '1.0'
+description: ActiveCampaign
+auth:
+  type: api_key
+  api_key:
+    env_var: ACTIVE-CAMPAIGN_API_KEY
+  required_fields:
+  - name: apiKey
+    label: API Key
+    placeholder: b4f1a7c9d8e56320a9db472fe6c8351f2e0a4d98b7f6c3e5d9a2f4701b3e8d6c3455abbe
+    input_type: text
+    help_text: The API Key for your ActiveCampaign account
+    optional: false
+  - name: hostname
+    label: Hostname
+    placeholder: company.activehosted.com
+    input_type: url
+    help_text: The Hostname for your ActiveCampaign account
+    optional: false
+setup_guide_url: https://nango.dev/docs/integrations/all/active-campaign
+tool_source:
+  type: mcp
+  server_name: active-campaign
+  command: active-campaign-mcp-server

connectkit/connectors/acuity-scheduling.yaml

@@ -0,0 +1,20 @@
+name: acuity-scheduling
+display: Acuity Scheduling
+icon: acuity
+category: productivity
+version: '1.0'
+description: Acuity Scheduling
+auth:
+  type: oauth2
+  oauth2:
+    authorize_url: https://acuityscheduling.com/oauth2/authorize
+    token_url: https://acuityscheduling.com/oauth2/token
+    scopes:
+    - api-v1
+    token_env_var: ACUITY-SCHEDULING_ACCESS_TOKEN
+  required_fields: []
+setup_guide_url: https://nango.dev/docs/integrations/all/acuity-scheduling
+tool_source:
+  type: mcp
+  server_name: acuity-scheduling
+  command: acuity-scheduling-mcp-server

connectkit/connectors/addepar.yaml

@@ -0,0 +1,26 @@
+name: addepar
+display: Addepar (OAuth)
+icon: addepar
+category: analytics
+version: '1.0'
+description: Addepar (OAuth)
+auth:
+  type: oauth2
+  oauth2:
+    authorize_url: https://id.addepar.com/oauth2/authorize
+    token_url: https://api.addepar.com/public/oauth2/token
+    scopes:
+    - read
+    token_env_var: ADDEPAR_ACCESS_TOKEN
+  required_fields:
+  - name: firmid
+    label: Firm ID
+    placeholder: ''
+    input_type: text
+    help_text: Your Addepar Firm ID
+    optional: false
+setup_guide_url: https://nango.dev/docs/integrations/all/addepar
+tool_source:
+  type: mcp
+  server_name: addepar
+  command: addepar-mcp-server

connectkit/connectors/adobe-commerce.yaml

@@ -0,0 +1,34 @@
+name: adobe-commerce
+display: Adobe Commerce
+icon: adobe
+category: e-commerce
+version: '1.0'
+description: Adobe Commerce
+auth:
+  type: api_key
+  api_key:
+    env_var: ADOBE-COMMERCE_API_KEY
+  required_fields:
+  - name: apiKey
+    label: Access Token
+    placeholder: 3pgsytnpxbyz0waujkw9qllcjb79s379
+    input_type: text
+    help_text: Your Adobe Commerce access token
+    optional: false
+  - name: storedomain
+    label: Store Domain
+    placeholder: yourstore.com
+    input_type: url
+    help_text: The domain of your Adobe Commerce store
+    optional: false
+  - name: storecode
+    label: Store Code
+    placeholder: default
+    input_type: text
+    help_text: The store code for your Adobe Commerce store
+    optional: false
+setup_guide_url: https://nango.dev/docs/api-integrations/adobe-commerce
+tool_source:
+  type: mcp
+  server_name: adobe-commerce
+  command: adobe-commerce-mcp-server

connectkit/connectors/adobe-workfront.yaml

@@ -0,0 +1,26 @@
+name: adobe-workfront
+display: Adobe Workfront
+icon: adobe
+category: productivity
+version: '1.0'
+description: Adobe Workfront
+auth:
+  type: oauth2
+  oauth2:
+    authorize_url: https://${connectionConfig.hostname}/integrations/oauth2/authorize
+    token_url: https://${connectionConfig.hostname}/integrations/oauth2/api/v1/token
+    scopes:
+    - read
+    token_env_var: ADOBE-WORKFRONT_ACCESS_TOKEN
+  required_fields:
+  - name: hostname
+    label: Hostname
+    placeholder: acme.my.workfront.com
+    input_type: text
+    help_text: The hostname of your Adobe Workfront account
+    optional: false
+setup_guide_url: https://nango.dev/docs/integrations/all/adobe-workfront
+tool_source:
+  type: mcp
+  server_name: adobe-workfront
+  command: adobe-workfront-mcp-server

connectkit/connectors/adobe.yaml

@@ -0,0 +1,20 @@
+name: adobe
+display: Adobe
+icon: adobe
+category: design
+version: '1.0'
+description: Adobe
+auth:
+  type: oauth2
+  oauth2:
+    authorize_url: https://ims-na1.adobelogin.com/ims/authorize/v2
+    token_url: https://ims-na1.adobelogin.com/ims/token/v3
+    scopes:
+    - offline_access
+    token_env_var: ADOBE_ACCESS_TOKEN
+  required_fields: []
+setup_guide_url: https://nango.dev/docs/integrations/all/adobe
+tool_source:
+  type: mcp
+  server_name: adobe
+  command: adobe-mcp-server

connectkit/connectors/adyen.yaml

@@ -0,0 +1,32 @@
+name: adyen
+display: Adyen
+icon: adyen
+category: payment
+version: '1.0'
+description: Adyen
+auth:
+  type: oauth2
+  oauth2:
+    authorize_url: https://ca-${connectionConfig.environment}.adyen.com/ca/ca/oauth/connect.shtml
+    token_url: https://oauth-${connectionConfig.environment}.adyen.com/v1/token
+    scopes:
+    - read
+    token_env_var: ADYEN_ACCESS_TOKEN
+  required_fields:
+  - name: environment
+    label: Environment
+    placeholder: live|test
+    input_type: text
+    help_text: The environment to use
+    optional: false
+  - name: resource
+    label: Resource
+    placeholder: kyc
+    input_type: text
+    help_text: The resource to use for your various requests
+    optional: false
+setup_guide_url: https://nango.dev/docs/integrations/all/adyen
+tool_source:
+  type: mcp
+  server_name: adyen
+  command: adyen-mcp-server

connectkit/connectors/affinity-v2.yaml

@@ -0,0 +1,22 @@
+name: affinity-v2
+display: Affinity (v2)
+icon: affinity
+category: crm
+version: '1.0'
+description: Affinity (v2)
+auth:
+  type: api_key
+  api_key:
+    env_var: AFFINITY-V2_API_KEY
+  required_fields:
+  - name: apiKey
+    label: API Key
+    placeholder: nrlW2KR5m-qUCA-rTqKb_EUK1swERlenqn70KNMMrTM
+    input_type: text
+    help_text: The API Key for your Affinity account
+    optional: false
+setup_guide_url: https://nango.dev/docs/integrations/all/affinity-v2
+tool_source:
+  type: mcp
+  server_name: affinity-v2
+  command: affinity-v2-mcp-server