agentvee-mcp 0.1.2__tar.gz

agentvee_mcp-0.1.2/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/

agentvee_mcp-0.1.2/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: agentvee-mcp
+Version: 0.1.2
+Summary: MCP server for AgentVee — file uploads for AI agents
+Project-URL: Homepage, https://agentvee.io
+Project-URL: Repository, https://github.com/agentvee/agentvee
+License-Expression: MIT
+Keywords: agentvee,ai-agents,file-upload,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# crabtransfer-mcp
+
+MCP server for [CrabTransfer](https://crabtransfer.com) — file uploads for AI agents with local `filePath` support.
+
+> **Note:** This is currently a test version. Full launch coming soon.
+
+## Quick Start
+
+1. **Get an API key** at [crabtransfer.com/dashboard](https://crabtransfer.com/dashboard)
+
+1. **Add to your MCP config** (e.g. `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "crabtransfer": {
+      "command": "uvx",
+      "args": ["crabtransfer-mcp"],
+      "env": {
+        "CRABTRANSFER_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Or with `pip`:
+
+```json
+{
+  "mcpServers": {
+    "crabtransfer": {
+      "command": "python",
+      "args": ["-m", "crabtransfer_mcp"],
+      "env": {
+        "CRABTRANSFER_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+1. **Restart your MCP client** (Cursor, Claude Desktop, etc.)
+
+## Installation
+
+```bash
+pip install crabtransfer-mcp
+```
+
+Or with uv:
+
+```bash
+uvx crabtransfer-mcp --help
+```
+
+## Supported Clients
+
+Any MCP client that supports stdio transport:
+
+- [Cursor](https://cursor.sh)
+- [Claude Desktop](https://claude.ai/download)
+- [Cline](https://github.com/cline/cline)
+- [Continue](https://continue.dev)
+
+## Available Tools
+
+| Tool                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `upload_and_wait`   | Upload a file and wait for a shareable download link |
+| `upload_file`       | Upload a file (returns upload ID for status polling) |
+| `upload_from_url`   | Upload a file from a public URL                      |
+| `get_upload_status` | Check the status of an upload                        |
+| `get_download_url`  | Get the download URL for a completed upload          |
+
+### Upload Methods
+
+Each upload tool supports three mutually exclusive input methods:
+
+- **`filePath`** — Local file path (stdio only, most efficient for local files — zero tokens)
+- **`url`** — Public URL for the server to fetch
+- **`content`** — Base64-encoded file content (fallback, uses tokens)
+
+## Environment Variables
+
+| Variable                    | Required | Default                                    | Description               |
+| --------------------------- | -------- | ------------------------------------------ | ------------------------- |
+| `CRABTRANSFER_API_KEY`      | Yes      | —                                          | Your CrabTransfer API key |
+| `CRABTRANSFER_API_BASE_URL` | No       | `https://crabtransfer-api-develop.fly.dev` | API base URL              |
+
+## CLI
+
+```bash
+crabtransfer-mcp --help
+crabtransfer-mcp --version
+```
+
+## HTTP Transport
+
+To run as an HTTP server (Streamable HTTP):
+
+```bash
+crabtransfer-mcp-http
+```
+
+Or:
+
+```bash
+python -m crabtransfer_mcp.http
+```
+
+## Also Available
+
+- **Node.js:** `npx -y @crabtransfer/mcp` ([npm](https://www.npmjs.com/package/@crabtransfer/mcp))
+
+## License
+
+MIT

agentvee_mcp-0.1.2/README.md

@@ -0,0 +1,118 @@
+# crabtransfer-mcp
+
+MCP server for [CrabTransfer](https://crabtransfer.com) — file uploads for AI agents with local `filePath` support.
+
+> **Note:** This is currently a test version. Full launch coming soon.
+
+## Quick Start
+
+1. **Get an API key** at [crabtransfer.com/dashboard](https://crabtransfer.com/dashboard)
+
+1. **Add to your MCP config** (e.g. `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "crabtransfer": {
+      "command": "uvx",
+      "args": ["crabtransfer-mcp"],
+      "env": {
+        "CRABTRANSFER_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Or with `pip`:
+
+```json
+{
+  "mcpServers": {
+    "crabtransfer": {
+      "command": "python",
+      "args": ["-m", "crabtransfer_mcp"],
+      "env": {
+        "CRABTRANSFER_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+1. **Restart your MCP client** (Cursor, Claude Desktop, etc.)
+
+## Installation
+
+```bash
+pip install crabtransfer-mcp
+```
+
+Or with uv:
+
+```bash
+uvx crabtransfer-mcp --help
+```
+
+## Supported Clients
+
+Any MCP client that supports stdio transport:
+
+- [Cursor](https://cursor.sh)
+- [Claude Desktop](https://claude.ai/download)
+- [Cline](https://github.com/cline/cline)
+- [Continue](https://continue.dev)
+
+## Available Tools
+
+| Tool                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `upload_and_wait`   | Upload a file and wait for a shareable download link |
+| `upload_file`       | Upload a file (returns upload ID for status polling) |
+| `upload_from_url`   | Upload a file from a public URL                      |
+| `get_upload_status` | Check the status of an upload                        |
+| `get_download_url`  | Get the download URL for a completed upload          |
+
+### Upload Methods
+
+Each upload tool supports three mutually exclusive input methods:
+
+- **`filePath`** — Local file path (stdio only, most efficient for local files — zero tokens)
+- **`url`** — Public URL for the server to fetch
+- **`content`** — Base64-encoded file content (fallback, uses tokens)
+
+## Environment Variables
+
+| Variable                    | Required | Default                                    | Description               |
+| --------------------------- | -------- | ------------------------------------------ | ------------------------- |
+| `CRABTRANSFER_API_KEY`      | Yes      | —                                          | Your CrabTransfer API key |
+| `CRABTRANSFER_API_BASE_URL` | No       | `https://crabtransfer-api-develop.fly.dev` | API base URL              |
+
+## CLI
+
+```bash
+crabtransfer-mcp --help
+crabtransfer-mcp --version
+```
+
+## HTTP Transport
+
+To run as an HTTP server (Streamable HTTP):
+
+```bash
+crabtransfer-mcp-http
+```
+
+Or:
+
+```bash
+python -m crabtransfer_mcp.http
+```
+
+## Also Available
+
+- **Node.js:** `npx -y @crabtransfer/mcp` ([npm](https://www.npmjs.com/package/@crabtransfer/mcp))
+
+## License
+
+MIT

agentvee_mcp-0.1.2/agentvee_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""AgentVee MCP server — file uploads for AI agents."""
+
+__version__ = "0.1.2"

agentvee_mcp-0.1.2/agentvee_mcp/__main__.py

@@ -0,0 +1,3 @@
+from agentvee_mcp.stdio import main
+
+main()

agentvee_mcp-0.1.2/agentvee_mcp/api_client.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from .config import mcp_config
+
+
+@dataclass
+class ApiOk:
+    ok: bool
+    status: int
+    data: dict[str, Any]
+
+    def __init__(self, status: int, data: dict[str, Any]):
+        self.ok = True
+        self.status = status
+        self.data = data
+
+
+@dataclass
+class ApiErr:
+    ok: bool
+    status: int
+    code: str
+    message: str
+    retry_after_sec: int | None = None
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        retry_after_sec: int | None = None,
+    ):
+        self.ok = False
+        self.status = status
+        self.code = code
+        self.message = message
+        self.retry_after_sec = retry_after_sec
+
+
+ApiResult = ApiOk | ApiErr
+
+
+def _map_error_message(
+    status: int,
+    code: str | None,
+    server_message: str | None,
+) -> str:
+    mapping: dict[str, str] = {
+        "rate_limit_exceeded": server_message or "Rate limit exceeded. Please wait and retry.",
+        "unauthorized": "Invalid or missing API key.",
+        "forbidden": "API key does not have required permissions.",
+        "size_limit_exceeded": f"File exceeds {mcp_config.max_file_size_bytes // (1024 * 1024)} MB limit.",
+        "blocked_mime_type": server_message or "File type not allowed.",
+        "empty_file": "File cannot be empty.",
+        "upload_worker_unavailable": "Upload service temporarily unavailable. Please retry.",
+        "storage_degraded": "Storage backend temporarily degraded. Please retry in 30s.",
+        "concurrency_limit_reached": "Too many concurrent uploads. Please wait and retry.",
+        "idempotency_in_progress": "A request with this idempotency key is already being processed.",
+        "invalid_url": server_message or "URL is not allowed.",
+        "ssrf_blocked": server_message or "URL is not allowed.",
+        "fetch_failed": server_message or "Failed to fetch file from URL.",
+        "fetch_timeout": "Timed out fetching file from URL.",
+        "upload_not_found": "Upload not found.",
+    }
+
+    if code and code in mapping:
+        return mapping[code]
+    if status >= 500:
+        return "Upload service error. Please retry."
+    return server_message or f"Request failed ({status})."
+
+
+def _parse_error(response: httpx.Response) -> ApiErr:
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+
+    error_obj = (body or {}).get("error", {}) if isinstance(body, dict) else {}
+    code = error_obj.get("code") or f"http_{response.status_code}"
+    server_message = error_obj.get("message")
+
+    retry_after_sec = error_obj.get("retryAfterSec")
+    if retry_after_sec is None:
+        raw_retry = response.headers.get("Retry-After")
+        if raw_retry:
+            try:
+                retry_after_sec = int(raw_retry)
+            except ValueError:
+                pass
+
+    return ApiErr(
+        status=response.status_code,
+        code=code,
+        message=_map_error_message(response.status_code, code, server_message),
+        retry_after_sec=retry_after_sec,
+    )
+
+
+def _client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        timeout=httpx.Timeout(mcp_config.api_timeout_ms / 1000),
+    )
+
+
+async def api_get(path: str, agent_key: str) -> ApiResult:
+    url = f"{mcp_config.api_base_url}{path}"
+    async with _client() as client:
+        try:
+            resp = await client.get(url, headers={"X-Agent-Key": agent_key})
+        except httpx.TimeoutException:
+            return ApiErr(0, "timeout", f"Request timed out after {mcp_config.api_timeout_ms}ms")
+        except httpx.HTTPError as exc:
+            return ApiErr(0, "network_error", f"Upload service error: {exc}")
+
+        if resp.is_success:
+            return ApiOk(resp.status_code, resp.json())
+        return _parse_error(resp)
+
+
+async def api_post_json(
+    path: str,
+    agent_key: str,
+    body: dict[str, Any],
+    extra_headers: dict[str, str] | None = None,
+) -> ApiResult:
+    url = f"{mcp_config.api_base_url}{path}"
+    headers: dict[str, str] = {"X-Agent-Key": agent_key, "Content-Type": "application/json"}
+    if extra_headers:
+        headers.update(extra_headers)
+
+    async with _client() as client:
+        try:
+            resp = await client.post(url, headers=headers, json=body)
+        except httpx.TimeoutException:
+            return ApiErr(0, "timeout", f"Request timed out after {mcp_config.api_timeout_ms}ms")
+        except httpx.HTTPError as exc:
+            return ApiErr(0, "network_error", f"Upload service error: {exc}")
+
+        if resp.is_success:
+            return ApiOk(resp.status_code, resp.json())
+        return _parse_error(resp)
+
+
+async def api_post_multipart(
+    path: str,
+    agent_key: str,
+    file_data: bytes,
+    file_name: str,
+    mime_type: str = "application/octet-stream",
+    extra_headers: dict[str, str] | None = None,
+) -> ApiResult:
+    url = f"{mcp_config.api_base_url}{path}"
+    headers: dict[str, str] = {"X-Agent-Key": agent_key}
+    if extra_headers:
+        headers.update(extra_headers)
+
+    files = {"file": (file_name, file_data, mime_type)}
+
+    async with _client() as client:
+        try:
+            resp = await client.post(url, headers=headers, files=files)
+        except httpx.TimeoutException:
+            return ApiErr(0, "timeout", f"Request timed out after {mcp_config.api_timeout_ms}ms")
+        except httpx.HTTPError as exc:
+            return ApiErr(0, "network_error", f"Upload service error: {exc}")
+
+        if resp.is_success:
+            return ApiOk(resp.status_code, resp.json())
+        return _parse_error(resp)

agentvee_mcp-0.1.2/agentvee_mcp/auth.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class AuthContext:
+    agent_key: str
+    token_prefix: str
+
+
+def resolve_auth() -> AuthContext | None:
+    """Resolve API key from environment variable (stdio transport)."""
+    env_key = (os.environ.get("AGENTVEE_API_KEY") or "").strip()
+    if env_key:
+        return AuthContext(agent_key=env_key, token_prefix=env_key[:12])
+    return None

agentvee_mcp-0.1.2/agentvee_mcp/config.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Literal
+
+TransportMode = Literal["http", "stdio"]
+
+_transport_mode: TransportMode = "http"
+
+
+def set_transport_mode(mode: TransportMode) -> None:
+    global _transport_mode
+    _transport_mode = mode
+
+
+def get_transport_mode() -> TransportMode:
+    return _transport_mode
+
+
+def _optional_env(name: str, fallback: str) -> str:
+    val = (os.environ.get(name) or "").strip()
+    return val if val else fallback
+
+
+def _number_env(name: str, fallback: int) -> int:
+    raw = os.environ.get(name)
+    if not raw:
+        return fallback
+    try:
+        parsed = int(raw)
+        return parsed if parsed > 0 else fallback
+    except ValueError:
+        return fallback
+
+
+@dataclass(frozen=True)
+class ThrottleConfig:
+    upload_window_ms: int = 15 * 60 * 1000
+    upload_max_requests: int = 30
+    status_window_ms: int = 15 * 60 * 1000
+    status_max_requests: int = 120
+    download_url_window_ms: int = 15 * 60 * 1000
+    download_url_max_requests: int = 60
+
+
+@dataclass(frozen=True)
+class WaitConfig:
+    max_concurrent: int = 50
+    max_duration_ms: int = 120_000
+    poll_initial_ms: int = 2_000
+    poll_max_ms: int = 8_000
+    poll_backoff_factor: float = 1.5
+
+
+@dataclass(frozen=True)
+class SessionConfig:
+    max_total: int = 1000
+    max_per_token: int = 50
+    idle_timeout_ms: int = 5 * 60 * 1000
+
+
+@dataclass(frozen=True)
+class McpConfig:
+    api_base_url: str = ""
+    port: int = 8082
+    allowed_origins: list[str] = field(default_factory=list)
+    log_level: str = "info"
+    max_file_size_bytes: int = 5 * 1024 * 1024
+    api_timeout_ms: int = 60_000
+    metrics_token: str = ""
+    throttle: ThrottleConfig = field(default_factory=ThrottleConfig)
+    wait: WaitConfig = field(default_factory=WaitConfig)
+    session: SessionConfig = field(default_factory=SessionConfig)
+
+
+def _build_config() -> McpConfig:
+    origins_raw = _optional_env("MCP_ALLOWED_ORIGINS", "")
+    origins = [o.strip() for o in origins_raw.split(",") if o.strip()]
+
+    return McpConfig(
+        api_base_url=_optional_env(
+            "AGENTVEE_API_BASE_URL",
+            "https://agentvee-api-develop.fly.dev",
+        ).rstrip("/"),
+        port=_number_env("MCP_PORT", 8082),
+        allowed_origins=origins,
+        log_level=_optional_env("MCP_LOG_LEVEL", "info"),
+        max_file_size_bytes=5 * 1024 * 1024,
+        api_timeout_ms=_number_env("MCP_API_TIMEOUT_MS", 60_000),
+        metrics_token=_optional_env("MCP_METRICS_TOKEN", ""),
+        throttle=ThrottleConfig(),
+        wait=WaitConfig(
+            max_concurrent=_number_env("MCP_WAIT_MAX_CONCURRENT", 50),
+            max_duration_ms=_number_env("MCP_WAIT_MAX_DURATION_MS", 120_000),
+            poll_initial_ms=_number_env("MCP_WAIT_POLL_INITIAL_MS", 2_000),
+            poll_max_ms=_number_env("MCP_WAIT_POLL_MAX_MS", 8_000),
+        ),
+        session=SessionConfig(
+            max_total=_number_env("MCP_SESSION_MAX_TOTAL", 1000),
+            max_per_token=_number_env("MCP_SESSION_MAX_PER_TOKEN", 50),
+            idle_timeout_ms=_number_env("MCP_SESSION_IDLE_TIMEOUT_MS", 5 * 60 * 1000),
+        ),
+    )
+
+
+mcp_config = _build_config()

agentvee_mcp-0.1.2/agentvee_mcp/http.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import sys
+
+from .config import mcp_config, set_transport_mode
+from .security.audit import audit_log
+from .server import create_mcp_server
+
+
+def main() -> None:
+    set_transport_mode("http")
+    server = create_mcp_server()
+    audit_log({"event": "startup", "transport": "streamable-http", "port": mcp_config.port})
+    server.run(transport="streamable-http", host="0.0.0.0", port=mcp_config.port)
+
+
+if __name__ == "__main__":
+    main()

agentvee_mcp-0.1.2/agentvee_mcp/security/audit.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+
+def audit_log(entry: dict[str, Any]) -> None:
+    record = {"ts": datetime.now(timezone.utc).isoformat(), **entry}
+    print(json.dumps(record, default=str), file=sys.stderr, flush=True)
+
+
+def sanitize_args(tool_name: str, args: dict[str, Any]) -> dict[str, Any]:
+    """Sanitize tool arguments for logging — never log tokens or large payloads."""
+    safe: dict[str, Any] = {}
+    for key, value in args.items():
+        if key == "content" and isinstance(value, str):
+            safe["contentSizeBytes"] = len(value) * 3 // 4
+            continue
+        if isinstance(value, str) and len(value) > 200:
+            safe[key] = f"{value[:50]}...[{len(value)} chars]"
+            continue
+        safe[key] = value
+    return safe

agentvee_mcp-0.1.2/agentvee_mcp/security/metrics.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+_started_at = time.monotonic()
+_total_requests = 0
+_auth_failures = 0
+_throttle_rejections = 0
+
+
+@dataclass
+class _ToolMetrics:
+    calls: int = 0
+    errors: int = 0
+    total_latency_ms: float = 0
+
+
+_tool_metrics: dict[str, _ToolMetrics] = {}
+
+
+def _get_or_create(tool: str) -> _ToolMetrics:
+    if tool not in _tool_metrics:
+        _tool_metrics[tool] = _ToolMetrics()
+    return _tool_metrics[tool]
+
+
+def record_tool_call(tool: str, duration_ms: float, is_error: bool) -> None:
+    global _total_requests
+    _total_requests += 1
+    m = _get_or_create(tool)
+    m.calls += 1
+    m.total_latency_ms += duration_ms
+    if is_error:
+        m.errors += 1
+
+
+def record_auth_failure() -> None:
+    global _auth_failures
+    _auth_failures += 1
+
+
+def record_throttle_rejection() -> None:
+    global _throttle_rejections
+    _throttle_rejections += 1
+
+
+def metrics_snapshot(active_sessions: int = 0, active_waits: int = 0) -> dict[str, Any]:
+    tools: dict[str, Any] = {}
+    for name, m in _tool_metrics.items():
+        tools[name] = {
+            "calls": m.calls,
+            "errors": m.errors,
+            "avgLatencyMs": round(m.total_latency_ms / m.calls) if m.calls > 0 else 0,
+        }
+
+    return {
+        "uptimeSeconds": int(time.monotonic() - _started_at),
+        "activeSessions": active_sessions,
+        "activeWaits": active_waits,
+        "totalRequests": _total_requests,
+        "authFailures": _auth_failures,
+        "throttleRejections": _throttle_rejections,
+        "tools": tools,
+    }

agentvee_mcp-0.1.2/agentvee_mcp/security/sessions.py

@@ -0,0 +1,9 @@
+"""Session tracking placeholder for HTTP transport compatibility."""
+
+from __future__ import annotations
+
+_session_count = 0
+
+
+def session_count() -> int:
+    return _session_count