Metadata-Version: 2.4
Name: lucidlink-mcp
Version: 0.0.2
Summary: Model Context Protocol server for LucidLink filespaces
Author: LucidLink
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://www.lucidlink.com
Project-URL: Documentation, https://www.lucidlink.com
Keywords: mcp,lucidlink,llm,ai,agent,filesystem
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: lucidlink==0.10.0
Requires-Dist: mcp>=1.6
Requires-Dist: watchdog>=4.0
Requires-Dist: certifi>=2024.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# LucidLink MCP Server (beta)

Connect AI agents (Claude Code, Codex, Cursor, and other MCP clients)
to a LucidLink filespace - read, write, search, lock, manage users and audit files in
natural language.

## Prerequisites

- A LucidLink service-account token (`sa_live:...`) for a filespace you can
  safely test in. Your LucidLink workspace admin can mint one - see
  [Service Accounts](https://support.lucidlink.com/hc/en-us/articles/40222074543757-Getting-Started-with-Service-Accounts-API-Authentication).
- Node.js 22+ on PATH - *only* for the admin tools (workspace, members,
  permissions). The file tools need no Node.

You don't need Python set up in advance; uv brings its own.

## Install

The client configs below launch the server with `uvx`, so the only thing to
install is [uv](https://docs.astral.sh/uv/) (it brings its own Python, no
separate setup):

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex
```

Reload your PATH so `uvx` is found: open a new terminal (on macOS/Linux you can
instead `source $HOME/.local/bin/env` in the current shell). If uv warns about
PATH later, run `uv tool update-shell`.
`uvx lucidlink-mcp` fetches and caches the package on first run, so there's no
separate install step. Check it works:

```bash
uvx lucidlink-mcp --version
```

Prefer a bare `lucidlink-mcp` command (to pin a version, or to keep `uvx` out of
your config)? Install it with `uv tool install lucidlink-mcp`, or
`pip install lucidlink-mcp` into a Python 3.10+ environment. Then use
`lucidlink-mcp` wherever the configs below say `uvx lucidlink-mcp`.

## Configure your token

```bash
uvx --from lucidlink-mcp lucidlink-mcp-setup
```

Prompts for the token, validates it, and stores it in
`~/.lucidlink/mcp-config.json` (mode 0600), so no client config has to carry it.
(Installed the bare command? Just run `lucidlink-mcp-setup`. Prefer not to use
the setup tool at all? See [Fallbacks](#fallbacks--troubleshooting) below.)

That's the whole setup. If your account sees several filespaces, the agent lists
them on first use and you tell it which to link, or pin a default with
`LUCIDLINK_FILESPACE` (see [Settings](#settings)).

## Register with your client

**Claude Code** - via the CLI:

```bash
claude mcp add lucidlink -s user -- uvx lucidlink-mcp
```

...or in `.mcp.json` at the project root (shareable; Claude Code asks to approve it once):

```json
{
  "mcpServers": {
    "lucidlink": {
      "command": "uvx",
      "args": ["lucidlink-mcp"]
    }
  }
}
```

Add options as env vars - `-e LUCIDLINK_MCP_TOOLSETS=admin` (CLI) or an `"env"` object
(JSON); see [Settings](#settings) below for the full list.

**Codex** - via the CLI:

```bash
codex mcp add lucidlink -- uvx lucidlink-mcp
```

...or in `~/.codex/config.toml`:

```toml
[mcp_servers.lucidlink]
command = "uvx"
args = ["lucidlink-mcp"]
```

Add options as env vars - `--env LUCIDLINK_MCP_TOOLSETS=admin` (CLI) or a
`[mcp_servers.lucidlink.env]` table (TOML); see [Settings](#settings) below. The token comes from
`~/.lucidlink/mcp-config.json` (via `lucidlink-mcp-setup`), so no `LUCIDLINK_TOKEN` is needed here.

**Cursor** - `~/.cursor/mcp.json` (global) or `<project>/.cursor/mcp.json` (per-project):

```json
{
  "mcpServers": {
    "lucidlink": {
      "command": "uvx",
      "args": ["lucidlink-mcp"]
    }
  }
}
```

Add an `"env"` object for options, e.g. `"env": { "LUCIDLINK_MCP_TOOLSETS": "admin" }`. If
Cursor can't find `uvx`, give its absolute path (`command -v uvx`).

## Settings

All optional except the token. Put them in the `env` block of your client's
server entry.

| Variable | Effect |
| --- | --- |
| `LUCIDLINK_TOKEN` | the token (or set it once via `lucidlink-mcp-setup` and omit this) |
| `LUCIDLINK_FILESPACE` | default filespace to link when several are visible |
| `LUCIDLINK_MCP_TOOLSETS` | `admin` adds workspace-management tools; `core` trims to 14 essential file tools |
| `LUCIDLINK_MCP_READ_ONLY` | `1` registers only read/search tools; nothing can write |
| `LUCIDLINK_MCP_NODE` | absolute path to a Node 22+ binary, if the admin tools can't find `node` |

## Try it

Ask your agent:

- "List my LucidLink filespaces", then "show me the files in /"
- "Create /beta-test/hello.txt with a short note, then read it back"
- "Search the filespace for files named hello.txt" (finds the file you just made)

## Connect an S3 data store (optional)

Link existing S3 objects into the filespace (read-only). S3 keys never reach the
agent - put them in `~/.lucidlink/data-stores.json` (mode 0600), keyed by store name:

```json
{ "my-store": { "access_key": "AKIA...", "secret_key": "...",
                "bucket_name": "my-bucket", "region": "us-east-1" } }
```

Then ask the agent to register the store (`register_data_store`) and link an
object (`link_external_file`). Needs a filespace at V9+ with Connect enabled;
see the project README for the rest.

## Enabling the audit trail (optional)

The agent can answer *who changed which files, and when* once the filespace's
audit trail is on. It's off by default, and enabling it needs filespace-admin
rights:

- On a machine with the desktop client connected, a
  filespace admin runs `lucid config --global --set --Audit.FsEvents 1`
  ([details](https://support.lucidlink.com/hc/en-us/articles/31125255979533-Audit-Trail-with-New-LucidLink)).

---

## Fallbacks & troubleshooting

**Set the token without the setup tool** - two equivalents:

- Write `~/.lucidlink/mcp-config.json` yourself as `{ "token": "sa_live:..." }`
  and `chmod 600` it.
- Or put `"env": { "LUCIDLINK_TOKEN": "sa_live:..." }` in your client's server
  entry.

**Command not found, or client shows "disconnected"?** The launcher (`uvx`, or
`lucidlink-mcp` if you installed the bare command) isn't on the PATH your client
sees, common with GUI clients that start from a minimal PATH. Put its absolute
path in the config; `command -v uvx` (or `command -v lucidlink-mcp`) prints it.
As a last resort, run the server module directly: `python3 -m lucidlink_mcp`.
