unlost-mcp 0.1.0__tar.gz

unlost_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/

unlost_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+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 → 集成里吊销即可。

unlost_mcp-0.1.0/README.md

@@ -0,0 +1,93 @@
+# 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 → 集成里吊销即可。

unlost_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "unlost-mcp"
+version = "0.1.0"
+description = "MCP server for unlost machine APIs via API Token"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "cyetstar" }]
+keywords = ["mcp", "unlost", "telegram", "discord"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.9.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/cyetstar/unlost"
+Repository = "https://github.com/cyetstar/unlost"
+Documentation = "https://github.com/cyetstar/unlost/tree/main/mcp"
+Issues = "https://github.com/cyetstar/unlost/issues"
+
+[project.scripts]
+unlost-mcp = "unlost_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/unlost_mcp"]

unlost_mcp-0.1.0/src/unlost_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""unlost MCP server — API Token HTTP bridge for Cursor / other MCP hosts."""
+
+__version__ = "0.1.0"

unlost_mcp-0.1.0/src/unlost_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m unlost_mcp` / `uv run python -m unlost_mcp`."""
+
+from unlost_mcp.server import main
+
+if __name__ == "__main__":
+    main()

unlost_mcp-0.1.0/src/unlost_mcp/client.py

@@ -0,0 +1,32 @@
+"""HTTP client for unlost machine API (``/api/v1``) used by MCP tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class UnlostApiError(Exception):
+    def __init__(self, status_code: int, detail: object):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"{status_code}: {detail}")
+
+
+class UnlostApiClient:
+    def __init__(self, base_url: str, token: str):
+        self._base = base_url.rstrip("/")
+        self._token = token
+
+    async def get(self, path: str, *, params: dict[str, Any] | None = None) -> str:
+        """GET and return response text; raise ``UnlostApiError`` on 4xx/5xx."""
+        async with httpx.AsyncClient(base_url=self._base, timeout=60.0) as client:
+            resp = await client.get(
+                path,
+                headers={"Authorization": f"Bearer {self._token}"},
+                params=params or {},
+            )
+            if resp.is_error:
+                raise UnlostApiError(resp.status_code, resp.text or f"HTTP {resp.status_code}")
+            return resp.text

unlost_mcp-0.1.0/src/unlost_mcp/server.py

@@ -0,0 +1,116 @@
+"""stdio MCP server: list_chats / fetch_messages → unlost v1 HTTP API."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+import httpx
+from unlost_mcp.client import UnlostApiClient, UnlostApiError
+
+# Prefer current SDK surface; fall back to FastMCP for older mcp packages.
+try:
+    from mcp.server import MCPServer as _Server
+except ImportError:  # pragma: no cover
+    from mcp.server.fastmcp import FastMCP as _Server
+
+mcp = _Server("unlost")
+
+_client: UnlostApiClient | None = None
+
+
+def _require_env() -> UnlostApiClient:
+    base_url = os.environ.get("UNLOST_BASE_URL", "").strip()
+    token = os.environ.get("UNLOST_API_TOKEN", "").strip()
+    missing: list[str] = []
+    if not base_url:
+        missing.append("UNLOST_BASE_URL")
+    if not token:
+        missing.append("UNLOST_API_TOKEN")
+    if missing:
+        names = ", ".join(missing)
+        print(
+            f"error: missing required environment variable(s): {names}\n"
+            "Set them before starting unlost-mcp, e.g.:\n"
+            "  export UNLOST_BASE_URL=http://127.0.0.1:8000\n"
+            "  export UNLOST_API_TOKEN=<api-token>",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    return UnlostApiClient(base_url, token)
+
+
+def get_client() -> UnlostApiClient:
+    global _client
+    if _client is None:
+        _client = _require_env()
+    return _client
+
+
+def _drop_none(params: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}
+
+
+async def _get(path: str, params: dict[str, Any] | None = None) -> str:
+    """GET JSON; on HTTP/transport errors return the raw body / message text."""
+    try:
+        return await get_client().get(path, params=params)
+    except UnlostApiError as exc:
+        return str(exc.detail) if exc.detail else f"HTTP {exc.status_code}"
+    except httpx.HTTPError as exc:
+        return str(exc)
+
+
+@mcp.tool()
+async def list_chats(source: str | None = None) -> str:
+    """List watched chats from GET /api/v1/chats.
+
+    Args:
+        source: Optional platform filter (e.g. telegram, discord).
+    """
+    return await _get("/api/v1/chats", _drop_none({"source": source}))
+
+
+@mcp.tool()
+async def fetch_messages(
+    chat_id: int | None = None,
+    source: str | None = None,
+    date_from: str | None = None,
+    date_to: str | None = None,
+    after_id: int | None = None,
+    limit: int | None = None,
+) -> str:
+    """Fetch messages from GET /api/v1/messages (incremental or day window).
+
+    Args:
+        chat_id: Watched chat id.
+        source: Optional platform filter.
+        date_from: Inclusive lower bound (ISO-8601 datetime).
+        date_to: Inclusive upper bound (ISO-8601 datetime).
+        after_id: Return messages with id strictly greater than this (cursor).
+        limit: Max items to return.
+    """
+    return await _get(
+        "/api/v1/messages",
+        _drop_none(
+            {
+                "chat_id": chat_id,
+                "source": source,
+                "date_from": date_from,
+                "date_to": date_to,
+                "after_id": after_id,
+                "limit": limit,
+            }
+        ),
+    )
+
+
+def main() -> None:
+    # Fail fast before stdio handshake if env is incomplete.
+    get_client()
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()