Metadata-Version: 2.4
Name: agentdrive
Version: 0.0.1
Summary: Placeholder for AgentDrive's stdio MCP companion. Full release coming soon — see https://agentdrive.mnexa.ai.
Project-URL: Homepage, https://agentdrive.mnexa.ai
Author: AgentDrive
License: MIT
Keywords: agentdrive,claude,mcp,upload
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Description-Content-Type: text/markdown

# agentdrive

> **v0.0.1 is a name-claim placeholder.** Running `uvx agentdrive` today
> prints an info message and exits. The full stdio shim (the
> `upload(file_path, ...)` tool described below) ships with the next
> release. Until then, the **hosted** AgentDrive MCP at
> `https://agentdrive.mnexa.ai/mcp` already covers reads, search, and
> writes that don't need local-disk access.

Stdio MCP shim for [AgentDrive](https://agentdrive.mnexa.ai). Lets agents on stdio-capable hosts (Claude Desktop, Cursor, Claude Code, Windsurf, Zed) upload local files into your AgentDrive without base64-encoding bytes through the model's token stream.

The hosted AgentDrive MCP at `https://agentdrive.mnexa.ai/mcp` already provides `list_artifacts`, `read`, `grep`, `overview`, `lookup`, and the rest of the tool surface. This shim only adds **`upload(file_path, ...)`** — the one tool that benefits from running in the user's process (filesystem access). Use both servers side-by-side.

## Install + run

```bash
uvx agentdrive
```

Or:

```bash
pipx install agentdrive
agentdrive
```

## Configuration

Environment variables:

| Var | Required | Default | Notes |
|---|---|---|---|
| `AGENTDRIVE_API_KEY` | yes | — | Your `ad_live_…` key. Get it from [agentdrive.mnexa.ai/settings/api-keys](https://agentdrive.mnexa.ai/settings/api-keys). |
| `AGENTDRIVE_BASE_URL` | no | `https://agentdrive.mnexa.ai` | Override for staging/dev. |
| `AGENTDRIVE_TIMEOUT` | no | `60` | Per-upload timeout in seconds. |

## Host config

Add to your MCP host config alongside the hosted AgentDrive MCP. Example for Claude Code (`~/.claude.json` global, or `.mcp.json` per-project — or use `claude mcp add`):

```jsonc
{
  "mcpServers": {
    "agentdrive": {
      "url": "https://agentdrive.mnexa.ai/mcp",
      "headers": { "Authorization": "Bearer ad_live_..." }
    },
    "agentdrive-upload": {
      "command": "uvx",
      "args": ["agentdrive"],
      "env": { "AGENTDRIVE_API_KEY": "ad_live_..." }
    }
  }
}
```

The `agentdrive` server handles reads, search, and listings; the `agentdrive-upload` server handles file uploads. Your MCP host routes tool calls to whichever server registered each tool name.

## Using alongside other MCP servers

MCP hosts spawn every configured server in parallel and merge their tool catalogs. Just add more entries to `mcpServers` — mix stdio (`command` + `args`) and hosted (`url` + `headers`) freely:

```jsonc
{
  "mcpServers": {
    "agentdrive":         { "url": "https://agentdrive.mnexa.ai/mcp",
                            "headers": { "Authorization": "Bearer ad_live_..." } },
    "agentdrive-upload":  { "command": "uvx", "args": ["agentdrive"],
                            "env": { "AGENTDRIVE_API_KEY": "ad_live_..." } },

    "filesystem":   { "command": "npx",
                      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"] },
    "git":          { "command": "uvx", "args": ["mcp-server-git"] },
    "github":       { "url": "https://api.githubcopilot.com/mcp/",
                      "headers": { "Authorization": "Bearer ghp_..." } },
    "linear":       { "url": "https://mcp.linear.app/sse",
                      "headers": { "Authorization": "Bearer lin_..." } }
  }
}
```

Three things worth knowing:

- **Tool name collisions are namespaced by server.** If two servers expose `upload`, the host disambiguates (e.g. `agentdrive-upload__upload` vs `other__upload`). That's also why our two AgentDrive entries are named `agentdrive` and `agentdrive-upload` — distinct keys, distinct sources.
- **Tool count budget.** Each server contributes 5–15 tools; past ~50–80 total in a model's catalog, tool-selection accuracy starts to degrade. Prune what you're not using.
- **Config file location varies by host** — same JSON shape, different paths:
  - Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
  - Claude Code: `~/.claude.json` (global, or use `claude mcp add`) or `.mcp.json` (per-project)
  - Cursor: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project)
  - Windsurf: `~/.codeium/windsurf/mcp_config.json`
  - Zed: project `.zed/settings.json` under `context_servers`

## The `upload` tool

```
upload(
  file_path:       str,                     # local path; required
  path:            str | None = None,       # destination in drive; defaults to filename
  visibility:      "public" | "private" = "public",
  labels:          list[str] | None = None,
  metadata:        dict | None = None,
  source:          dict | None = None,      # v0.6 typed provenance
  actor_name:      str | None = None,
  change_summary:  str | None = None,
  content_type:    str | None = None,       # inferred from extension if omitted
  if_match:        int | None = None,       # optimistic concurrency
) -> dict
```

Returns the artifact JSON: `id`, `path`, `url`, `content_type`, `size_bytes`, `version_number`, `labels`, `source`, etc.

## How it works

The shim runs on your machine as a subprocess (stdio MCP server). When an agent calls `upload(file_path, ...)`:

1. The shim reads the bytes from local disk.
2. It PUTs them to `https://agentdrive.mnexa.ai/v0/artifacts/{path}` over HTTPS with your bearer token in the `Authorization` header.
3. Hosted AgentDrive stores the artifact, returns the metadata, and the shim returns it to the agent.

Bytes never traverse the model's token stream. The AgentDrive side enforces the usual 50 MB per-artifact cap, rate limits, and quotas.

## License

MIT.
