Metadata-Version: 2.4
Name: lucidlink-mcp
Version: 0.0.3
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 :: 4 - Beta
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`.

## License and usage

This MCP server (the “MCP Server”) is proprietary to LucidLink Corp. and is provided solely to enable you to install, run, and self-host the MCP Server, and to develop applications and integrations that interact with LucidLink services.

Use of this MCP Server is governed by the LucidLink Terms and Conditions available at: https://www.lucidlink.com/terms (the “LucidLink Terms”), or, if you or your organization have entered into a separate written agreement with LucidLink governing your use of LucidLink services (for example, a subscription agreement or master services agreement), such separate written agreement.

This MCP Server (including any associated example or sample code) is not licensed under an open‑source license. All rights are reserved by LucidLink except as expressly granted in the Applicable Terms.
