Admin API MCP

Claude桌面版LucidLink MCP服务器

概述

此MCP（模型上下文协议）服务器使非技术用户能够通过Claude Desktop for macOS中的自然语言对话与LucidLink Admin API容器进行交互。它处理Docker管理、API身份验证，并将会话请求转换为正确的API调用。

特性

🐳 Docker管理

• 自动Docker桌面检测和启动
• 容器生命周期管理
• 日志流和诊断

📁 文件空间操作

• 使用可自定义的区域和存储提供程序创建新的文件空间
• 列出并管理现有文件空间
• 通过安全确认删除文件空间

👥 用户和组管理

• 通过电子邮件添加成员
• 创建和管理组
• 在组中添加/删除成员

🔐 权限控制

• 授予读/写/管理权限
• 在文件夹级别管理访问权限
• 支持用户和组权限

🛡️ 安全与安保

• macOS Keychain中的安全令牌存储
• 输入验证和净化
• 限制利率以防止滥用
• 用户友好的错误消息

先决条件

• macOS （英特尔或苹果硅）
• LucidLink商业或企业计划
• 服务账户 具有API访问权限
• 紫外线 （Python包管理器）-通过install.sh自动安装
• Mac版Docker桌面

快速安装

1. 下载文件:

- lucidlink_mcp_server.py - pyproject.toml - install.sh

1. 运行安装程序:

   chmod +x install.sh
   ./install.sh

1. 按照提示操作 致：

- 安装Docker桌面（如果需要） - 输入您的持票人代币 - 配置Claude桌面

1. 重新启动克劳德桌面

手动安装

第一步：安装Docker桌面

下载自

第二步：获取您的持有者代币

1. 登录LucidLink管理门户
2. 导航至 服务账户
3. 创建或选择服务帐户
4. 生成一个 密钥 （这是您的持票人代币）

步骤3：安装uv和MCP服务器

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create installation directory
mkdir -p ~/lucidlink-mcp
cd ~/lucidlink-mcp

# Copy the server files
cp lucidlink_mcp_server.py ~/lucidlink-mcp/
cp pyproject.toml ~/lucidlink-mcp/

# Note: Dependencies are automatically installed when you first run the server with 'uv run'

# Store bearer token securely (optional but recommended)
security add-generic-password -a "bearer_token" -s "lucidlink-mcp" -w "YOUR_BEARER_TOKEN"

步骤4：配置Claude桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lucidlink-admin-api": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/lucidlink-mcp",
        "run",
        "python",
        "lucidlink_mcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

注：

• 使用完整路径 uv （通常 ~/.local/bin/uv)因为Claude Desktop没有继承终端的PATH
• 这 --directory flag告诉uv使用该目录中的pyproject.toml

步骤5：重新启动克劳德桌面

重新启动Claude Desktop以加载MCP服务器。

用法示例

首次设置

你：“检查Docker是否正在运行”

Claude检查Docker状态，并在需要时启动它

你：“拉容器图像”

Claude从Docker Hub中提取清醒链接/清醒链接api映像（需要时自动发生）

你：“初始化API”

Claude使用您的承载令牌建立API连接

创建资源

你：“创建一个名为营销资产的新文件空间”

Claude使用默认设置（AWS、us-east-1）创建文件空间

你：“在欧洲创建一个名为eu data的文件空间”

Claude在eu-west-1区域创建文件空间

你：“添加sarah@company.com到工作区”

Claude添加新成员

你：“创建一个名为设计团队的组”

Claude创建新组

管理权限

你：“允许设计团队阅读营销资产”

Claude授予该组读取权限

你：“授予管理员访问权限john@company.com欧盟数据文件空间

Claude授予用户管理员权限

查看信息

你：“显示所有文件空间”

Claude列出了所有文件空间及其详细信息

你：“列出所有成员”

Claude显示所有工作区成员

你：“对营销资产设置了哪些权限？”

Claude显示该文件空间的所有权限

自然语言模式

MCP服务器理解表达相同动作的各种方式：

创建文件空间

• “创建一个名为X的文件空间”
• “创建一个名为X的新文件空间”
• “为X设置文件空间”
• “我需要一个名为X的文件空间”

添加成员

• “添加user@email.com"
• “邀请user@email.com到工作区”
• “给user@email.com访问“
• “包括user@email.com作为会员”

授予权限

• “授予营销组对项目文件的读取权限”
• “让营销组查看项目文件”
• “向市场营销部门授予项目文件的读取权限”
• “营销人员应该能够阅读项目文件”

API终点

MCP服务器与以下LucidLink API端点交互：

配置

环境变量

• LUCIDLINK_BEARER_TOKEN：您的服务帐户持有者令牌
• DOCKER_CONTAINER_IMAGE：容器映像名称（默认：lucidlink-api容器：latest）
• PYTHONUNBUFFERED：设置为“1”以进行实时记录

存储承载令牌

选项1:macOS钥匙串（推荐）

security add-generic-password -a "bearer_token" -s "lucidlink-mcp" -w "YOUR_TOKEN"

选项2：环境变量

export LUCIDLINK_BEARER_TOKEN="your_token_here"

选项3:Claude桌面配置 添加到env部分 claude_desktop_config.json:

"env": {
  "LUCIDLINK_BEARER_TOKEN": "your_token_here"
}

故障排除

Docker问题

问题：“未安装Docker桌面”

• 解决方案：从Docker.com安装Docker桌面

问题：“Docker未运行”

• 解决方案：MCP服务器将尝试自动启动它。如果失败，请手动启动Docker Desktop。

问题：“容器无法启动”

• 解决方案：检查图像是否已加载： docker images | grep lucidlink

API连接问题

问题：“身份验证失败”

• 解决方案：验证您的持票人令牌是否正确且未过期

问题：“无法连接到API”

• 解决方案：确保容器在端口3003上运行： docker ps

问题：“超出费率限制”

• 解决方案：等待60秒以重置速率限制

Claude桌面问题

问题：“MCP服务器在Claude中不可用”

• 解决方案：更新配置文件后重新启动Claude Desktop

问题：“运行命令时出现Python错误”

• 解决方案：确保安装了所有依赖项： pip3 install -r requirements.txt

查看日志

集装箱日志:

docker logs lucidlink-api

MCP服务器日志: 检查Claude Desktop的开发人员控制台或手动运行服务器：

cd ~/lucidlink-mcp
uv run python lucidlink_mcp_server.py

安全最佳实践

1. 永远不要分享你的无记名代币
2. 使用macOS钥匙扣 用于令牌存储
3. 定期轮换 您的服务帐户令牌
4. 监控API使用情况 通过LucidLink管理门户
5. 限制权限 到最低限度

高级用法

定制存储提供商

# Modify the server to support additional providers
class StorageProvider(Enum):
    AWS = "AWS"
    AZURE = "Azure"
    GCP = "GCP"
    WASABI = "Wasabi"
    CUSTOM = "YourProvider"

批量操作

您可以扩展服务器以处理批量操作：

# Example: Bulk member addition
def add_members_bulk(self, emails: List[str]) -> List[ApiResponse]:
    responses = []
    for email in emails:
        responses.append(self.add_member(email))
    return responses

Webhook集成

Webhook允许您在发生API操作时向外部服务发送实时通知。这对于日志记录、触发Slack通知或与Zapier等自动化工具集成非常有用。

添加此方法以发送webhook通知：

def notify_webhook(self, event: str, data: Dict):
    webhook_url = os.getenv("WEBHOOK_URL")
    if webhook_url:
        requests.post(webhook_url, json={
            "event": event,
            "data": data,
            "timestamp": time.time()
        })

然后从要监视的操作中调用它：

def create_filespace(self, name: str, ...):
    response = self._make_request("POST", "/api/v1/filespaces", ...)
    self.notify_webhook("filespace_created", {"name": name, "id": response.data.get("id")})
    return response

支持

• API文档：请参阅API关键功能指南
• Docker帮助:

许可证

此MCP服务器是为LucidLink客户提供的，用于与他们的管理员API交互。

版本历史记录

v1.0.0（2024）

• API全面支持的初始版本
• Docker自动化
• 自然语言处理
• 安全令牌管理