Metadata-Version: 2.5
Name: unlost-mcp
Version: 0.1.0
Summary: MCP server for unlost machine APIs via API Token
Project-URL: Homepage, https://github.com/cyetstar/unlost
Project-URL: Repository, https://github.com/cyetstar/unlost
Project-URL: Documentation, https://github.com/cyetstar/unlost/tree/main/mcp
Project-URL: Issues, https://github.com/cyetstar/unlost/issues
Author: cyetstar
License-Expression: MIT
Keywords: discord,mcp,telegram,unlost
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.9.0
Description-Content-Type: text/markdown

# unlost-mcp

MCP server (stdio) that exposes unlost **machine APIs** (`GET /api/v1/chats`, `GET /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](https://docs.astral.sh/uv/)（推荐用 `uvx` / `uv run`）
- 可达的 unlost 后端（`UNLOST_BASE_URL`）
- API Token（Settings → 集成）

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

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

```json
{
  "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 后（可选）

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

```bash
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（维护者）

```bash
cd mcp
uv build
uv publish
```

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

## 4. Tools

| Tool | Maps to |
| --- | --- |
| `list_chats(source?)` | `GET /api/v1/chats` |
| `fetch_messages(chat_id?, source?, date_from?, date_to?, after_id?, limit?)` | `GET /api/v1/messages` |

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 → 集成里吊销即可。
