unlost-mcp

MCP server (stdio) that exposes unlost machine APIs (/api/v1/chats、/api/v1/messages 及媒体相关只读接口) to hosts such as Cursor, authenticated with an API Token from Settings → 集成.

Tools are read-only; summarization stays in the agent — there is no summarize tool.

Requirements

• Python 3.11+
• uv（推荐用 uvx / uv run）
• 可达的 unlost 后端（UNLOST_BASE_URL）
• API Token（Settings → 集成）

1. Cursor MCP（推荐：本地 uv run）

未发布到 PyPI 时，用 monorepo 里的包直接跑：

{
  "mcpServers": {
    "unlost": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABS/PATH/unlost/mcp",
        "run",
        "unlost-mcp"
      ],
      "env": {
        "UNLOST_BASE_URL": "http://127.0.0.1:8000",
        "UNLOST_API_TOKEN": "ul_...."
      }
    }
  }
}

发布到 PyPI 后（可选）

{
  "mcpServers": {
    "unlost": {
      "command": "uvx",
      "args": ["unlost-mcp"],
      "env": {
        "UNLOST_BASE_URL": "https://unlost.onelooker.cc",
        "UNLOST_API_TOKEN": "ul_...."
      }
    }
  }
}

固定版本示例："args": ["unlost-mcp==0.1.0"]。

2. Local install / debug

cd mcp
uv sync
export UNLOST_BASE_URL=http://127.0.0.1:8000
export UNLOST_API_TOKEN=ul_....
uv run unlost-mcp

stdio：等待 MCP host；缺环境变量时 stderr 提示并以 code 1 退出。

等价入口：uv run python -m unlost_mcp。

3. Publish to PyPI（维护者）

cd mcp
uv build
uv publish

发版前 bump pyproject.toml 的 version，再 uv build && uv publish。

4. Tools

media[] 字段含 kind、mime、size、file_name、width/height、status、公开 url（MinIO）。HTTP error bodies are returned as tool text (no extra wrapping).

5. Security

• Never commit UNLOST_API_TOKEN / PyPI token。
• Token 与 REST /api/v1、Webhook 共用；在 Settings → 集成里吊销即可。