Metadata-Version: 2.4
Name: klark-local-file-ops-mcp
Version: 0.2.1
Summary: Local stdio MCP companion for KLARK direct uploads. Pairs with the remote KLARK platform MCP to stream local files into KLARK via pre-signed Azure SAS URLs.
Author-email: Aker Yilmaz <aker@useklark.com>
Maintainer-email: "KLARK Inc." <aker@useklark.com>
License: KLARK Inc. Proprietary Software License
        
        Copyright (c) 2026 KLARK Inc. All rights reserved.
        
        This software ("Software") is the proprietary property of KLARK Inc. and is
        made available through public package registries solely to enable interop
        with KLARK Inc. products and services.
        
        Subject to the restrictions below, KLARK Inc. grants you a non-exclusive,
        non-transferable, revocable, royalty-free license to:
        
          (a) install and run the Software on systems under your control; and
          (b) use the Software as a client-side companion to interact with KLARK
              Inc. services for which you have a valid account or agreement.
        
        You may NOT, without prior written permission from KLARK Inc.:
        
          - modify, translate, adapt, or create derivative works of the Software;
          - reverse-engineer, decompile, or disassemble the Software except to the
            extent such restriction is prohibited by applicable law;
          - redistribute, sublicense, rent, lease, or sell the Software or any
            portion of it, in original or modified form;
          - use the Software to build or assist in building a product or service
            that competes with KLARK Inc.;
          - remove or alter any copyright, trademark, or proprietary notices.
        
        KLARK Inc. reserves the right to revoke this license at any time, to change
        its terms, or to release future versions under a different license.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
        KLARK INC. BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
        FROM THE USE OF THE SOFTWARE.
        
        For licensing inquiries: aker@useklark.com
        
Project-URL: Homepage, https://github.com/deniz-akbas/klark-local-file-ops-mcp
Project-URL: Repository, https://github.com/deniz-akbas/klark-local-file-ops-mcp
Project-URL: Issues, https://github.com/deniz-akbas/klark-local-file-ops-mcp/issues
Keywords: mcp,klark,file-upload,azure-blob,stdio
Classifier: Development Status :: 4 - Beta
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: azure-storage-blob>=12.19
Requires-Dist: fastmcp>=2.10
Requires-Dist: mcp>=1.1
Requires-Dist: pydantic>=2
Dynamic: license-file

# klark-local-file-ops-mcp

Local stdio MCP companion that lets your coding agent upload files from your
machine into KLARK. Pairs with the remote KLARK platform MCP — the remote
side reserves an upload slot, this local side streams the bytes.

---

## Use with Claude Code

### 1. Install `uv`

`uvx` (ships with `uv`) fetches this MCP on first call and caches it. No
per-project install step.

```bash
brew install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Add the MCP to your project

Create `.mcp.json` at the root of your project:

```json
{
  "mcpServers": {
    "klark-local-file-ops-mcp": {
      "command": "uvx",
      "args": ["klark-local-file-ops-mcp"]
    }
  }
}
```

Commit this file if you want teammates to pick up the same setup.

### 3. Restart Claude Code

Close and reopen your Claude Code session. On first launch you'll see:

> *"A new MCP server `klark-local-file-ops-mcp` is configured in `.mcp.json`. Approve?"*

Say yes. Claude Code runs `uvx klark-local-file-ops-mcp`, which fetches the
package from PyPI and starts the stdio server.

### 4. Try it

In the Claude Code chat, ask:

> Upload `~/Desktop/logo.png` to KLARK and show me the file ID

Claude Code will call:

1. `klark_platform.begin_upload` → reserves an Azure upload slot, returns a scoped SAS URL
2. `klark-local-file-ops-mcp.upload_local_file_via_session` → streams your file to the SAS URL
3. `klark_platform.finalize_upload` → registers the file in KLARK Drive, returns a `drive_file_id`

You'll see the `drive_file_id` in the reply and can reference the file in
later turns (`show me that file`, `attach it to …`).

---

## The remote KLARK MCP is a prerequisite

This package is the **local half** of a pair. The remote half —
`klark_platform` — must also be configured in Claude Code. If KLARK is
already wired into your setup (e.g., by your admin), `begin_upload` and
`finalize_upload` are already there. If not, add it alongside:

```json
{
  "mcpServers": {
    "klark_platform": {
      "type": "http",
      "url": "<KLARK_AI_URL>/klark-mcp/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    },
    "klark-local-file-ops-mcp": {
      "command": "uvx",
      "args": ["klark-local-file-ops-mcp"]
    }
  }
}
```

Ask your KLARK admin for the URL and a bearer token.

---

## Use with Codex

```bash
codex mcp add klark-local-file-ops-mcp -- uvx klark-local-file-ops-mcp
```

The prerequisite (`klark_platform`) and the upload flow are the same.

---

## Tools

| Tool | Purpose |
|---|---|
| `inspect_local_file(path)` | Stat a local file before upload — returns existence, size, sniffed content type, readability. |
| `upload_local_file_via_session(path, upload_target)` | Streams the local file to the SAS URL carried in `upload_target` (minted by `klark_platform.begin_upload`). Enforces `contract_version`. |

Both tools are stateless. They read local files; they do not write, move,
or delete anything on your machine.

---

## Troubleshooting

**"A new MCP server … Approve?" never appears**
You're on an older Claude Code. Update (`npm update -g @anthropic-ai/claude-code`) and restart.

**`uvx: command not found`**
`uv` isn't installed or isn't on PATH. `brew install uv`, then restart Claude Code.

**`CONTRACT_VERSION_MISMATCH` at upload time**
Your KLARK backend and this package are on incompatible versions. Upgrade: `uv cache prune` and restart Claude Code so `uvx` re-fetches the newest release.

**`LOCAL_FILE_NOT_FOUND`**
The agent used a bad path. Paths must be absolute and readable by your user account.

---

## Alternate install paths

If `uvx` doesn't fit your workflow:

```bash
# Pinned install (offline-friendly)
pipx install klark-local-file-ops-mcp
# then in .mcp.json use: "command": "klark-local-file-ops-mcp"

# Direct module run (for development)
python -m klark_local_file_ops_mcp
```

---

## License

KLARK Inc. Proprietary — see [`LICENSE`](./LICENSE). For licensing inquiries:
[aker@useklark.com](mailto:aker@useklark.com).
