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.

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:

{
  "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:

{
  "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

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:

# 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. For licensing inquiries: aker@useklark.com.