loomnote-mcp 0.1.0__py3-none-any.whl

loomnote_mcp/README.md

@@ -0,0 +1,71 @@
+# loomnote-mcp
+
+Loomnote 笔记的 MCP 服务端：在你自己的电脑上启动，用你自己的存储凭证直连你的
+笔记数据（本地磁盘 / 腾讯云 COS / S3 兼容存储），让 AI 客户端（Claude Code、
+Codex 等）读笔记、把笔记分发到公众号/小红书/微博/B站/Reddit/YouTube，并把
+发布结果写回一份回执文件。Loomnote 的服务器不在这条数据路径上。
+
+## 安全模型
+
+- **默认只读**。`record_publish_receipt` / `publish_note` /
+  `update_publish_receipt` 三个写工具始终注册（客户端能看到它们），但调用会
+  返回 `{"ok": false, "error": "..."}`，直到你加 `--allow-publish-writes`
+  重新启动。
+- **只写一个文件**：即使开了可写模式，唯一可能被写入的文件是
+  `publish-receipts.json`（发布回执）。笔记正文（`memos/`）、图片/视频
+  （`file/`）、模板（`templates/`）、配置（`.config.json`）在写入前就会被
+  拒绝，抛 `PermissionError`。
+- **没有删除功能**。这个 MCP 不提供、也不会去调用任何删除对象/文件的接口——
+  无论是否加 `--allow-publish-writes`。
+- **凭证只走环境变量**，从不出现在命令行参数或返回给 AI 客户端的内容里；
+  建议给 COS/S3 单独开一个只有读 + 对 `publish-receipts.json` 有写权限的
+  子账号密钥，而不是主账号全量密钥。
+
+## 安装
+
+```bash
+uvx loomnote-mcp --help          # 免安装直接跑
+# 或
+pipx install loomnote-mcp
+```
+
+## 启动
+
+```bash
+# 本地磁盘（memos/ 所在目录）
+uvx loomnote-mcp --source disk --notes-dir /path/to/memos
+
+# 腾讯云 COS
+export LOOMNOTE_COS_SECRET_ID=...
+export LOOMNOTE_COS_SECRET_KEY=...
+uvx loomnote-mcp --source cos --bucket <bucket> --region <region> --prefix <可选前缀>
+
+# 开启可写回执（默认关闭，见上面的安全模型）
+uvx loomnote-mcp --source cos --bucket <bucket> --region <region> --allow-publish-writes
+```
+
+参数一览：`--source {disk,cos,s3}`、`--notes-dir`（disk）、`--bucket` /
+`--region`（cos）/ `--endpoint`（s3 兼容）、`--prefix`、`--allow-publish-writes`、
+`--transport stdio`（目前只支持 stdio）。
+
+## 自检
+
+```bash
+uvx loomnote-mcp --source disk --notes-dir /path/to/memos --selfcheck
+# loomnote-mcp 已连通 · 数据源 disk(...) · N 条笔记 · 11 个工具 · 只读
+```
+
+`N` 应等于 Loomnote App 里的笔记总数；对不上说明没连到正确的数据源。
+
+## 客户端配置示例（Claude Code）
+
+```bash
+claude mcp add loomnote \
+  -e LOOMNOTE_COS_SECRET_ID=<你的子账号 SecretId> \
+  -e LOOMNOTE_COS_SECRET_KEY=<你的子账号 SecretKey> \
+  -- uvx loomnote-mcp --source cos --bucket <your-bucket> --region <your-region>
+```
+
+其他支持 stdio MCP 的客户端（Codex 等）同理，把上面的命令粘进各自的 MCP
+服务器配置里即可。Loomnote App 的「AI 接入」页会按你的实际存储配置生成这段
+命令，直接复制粘贴，不用手拼。

loomnote_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""loomnote-mcp: a small, source-agnostic MCP server for Loomnote notes.
+
+Reads notes and records multi-channel publish receipts from the user's own
+storage (local disk, or their COS/S3 bucket via `--source cos|s3`), in memory
+only — nothing is cached to disk when reading from an object store. See
+`docs/publish/publish-space-design.md` §3 for the design this implements.
+"""

loomnote_mcp/_notes.py

@@ -0,0 +1,28 @@
+"""Shared note-lookup helpers used by both loomnote_mcp/tools.py and
+loomnote_mcp/tools_publish_task.py. Split out so tools_publish_task.py doesn't
+have to import from tools.py (that would be circular: tools.py imports
+tools_publish_task.py to register its two tools).
+"""
+
+from __future__ import annotations
+
+import notes_core
+
+from .sources.base import NoteSource
+
+
+def read_note(source: NoteSource, note_id: str) -> dict:
+    if not note_id or not note_id.endswith(".md") or note_id.startswith("/") or ".." in note_id.split("/"):
+        raise ValueError(f"invalid note id: {note_id!r}")
+    text = source.read_document(note_id)
+    if text is None:
+        raise ValueError(f"note not found: {note_id!r}")
+    tags, created, body = notes_core.parse(text)
+    return {"id": note_id, "created": created, "tags": tags, "body": body}
+
+
+def try_read_note(source: NoteSource, note_id: str) -> tuple[dict | None, str]:
+    try:
+        return read_note(source, note_id), ""
+    except ValueError as e:
+        return None, str(e)

loomnote_mcp/cli.py

@@ -0,0 +1,133 @@
+"""loomnote-mcp command-line entry point.
+
+Parses --source/credentials, builds the matching NoteSource, and starts the
+MCP server over stdio. This is what `uvx loomnote-mcp --source cos ...` runs
+(see docs/publish/publish-space-design.md §3.2 for the end-to-end story).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .sources.base import NoteSource
+from .sources.cos import CosSource, build_client
+from .sources.disk import DiskSource
+
+_COS_ENV_ID = "LOOMNOTE_COS_SECRET_ID"
+_COS_ENV_KEY = "LOOMNOTE_COS_SECRET_KEY"
+
+
+def build_arg_parser(*, include_selfcheck: bool = False) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="loomnote-mcp", description="Loomnote MCP server (stdio)")
+    parser.add_argument("--source", choices=["disk", "cos", "s3"], default="disk")
+    parser.add_argument(
+        "--notes-dir",
+        dest="notes_dir",
+        default=os.path.join(os.getcwd(), "memos"),
+        help="disk source only: the memos/ directory path",
+    )
+    parser.add_argument("--bucket", default=None, help="cos/s3 source: bucket name")
+    parser.add_argument("--region", default=None, help="cos source: region, e.g. ap-shanghai")
+    parser.add_argument("--prefix", default="", help="cos/s3 source: root key prefix (default: none)")
+    parser.add_argument(
+        "--endpoint",
+        default=None,
+        help="s3 source: endpoint URL (cos source derives this from --region instead)",
+    )
+    parser.add_argument("--transport", default="stdio", choices=["stdio"])
+    parser.add_argument(
+        "--allow-publish-writes",
+        dest="allow_publish_writes",
+        action="store_true",
+        help=(
+            "Allow record_publish_receipt/publish_note/update_publish_receipt to actually "
+            "write publish-receipts.json. Default: off (read-only) — those three tools "
+            "still register, but each call returns {ok: false, error} until this is set. "
+            "Loomnote's 'AI 接入' page shows the exact command once AI 代发 is turned on."
+        ),
+    )
+    if include_selfcheck:
+        parser.add_argument(
+            "--selfcheck",
+            action="store_true",
+            help="Verify the source is reachable and print a summary; exit 0 on success.",
+        )
+    return parser
+
+
+def build_source(args: argparse.Namespace) -> NoteSource:
+    if args.source == "disk":
+        return DiskSource(args.notes_dir)
+    return _build_object_store_source(args)
+
+
+def _build_object_store_source(args: argparse.Namespace) -> CosSource:
+    if not args.bucket:
+        _fail("缺少 --bucket 参数")
+    if args.source == "cos" and not args.region and not args.endpoint:
+        _fail("COS 数据源需要 --region（或 --endpoint）")
+
+    access_key_id = os.environ.get(_COS_ENV_ID)
+    secret_access_key = os.environ.get(_COS_ENV_KEY)
+    if not access_key_id or not secret_access_key:
+        _fail(f"缺少凭证：请设置环境变量 {_COS_ENV_ID} 和 {_COS_ENV_KEY}")
+
+    client = build_client(
+        region=args.region,
+        endpoint=args.endpoint,
+        access_key_id=access_key_id,
+        secret_access_key=secret_access_key,
+    )
+    return CosSource(client, args.bucket, args.prefix)
+
+
+def _fail(message: str) -> None:
+    print(f"loomnote-mcp: {message}", file=sys.stderr)
+    sys.exit(2)
+
+
+def _source_label(args: argparse.Namespace) -> str:
+    """The "数据源 ..." segment of the --selfcheck summary line."""
+    if args.source == "disk":
+        return f"disk({args.notes_dir})"
+    kind = "COS" if args.source == "cos" else "S3"
+    return f"{kind}(bucket={args.bucket}, region={args.region})"
+
+
+def _selfcheck(args: argparse.Namespace, source: NoteSource, tool_names: list[str]) -> int:
+    """Connect once, print a one-line Chinese summary, exit 0/1 (credential
+    errors already exited 2 earlier, in build_source)."""
+    try:
+        note_count = len(source.load_notes())
+    except Exception as exc:  # any backend's connection/auth/parse failure
+        print(f"连接失败：{exc}", file=sys.stderr)
+        return 1
+    write_mode = "可写回执" if getattr(args, "allow_publish_writes", False) else "只读"
+    print(
+        f"loomnote-mcp 已连通 · 数据源 {_source_label(args)} · {note_count} 条笔记 · "
+        f"{len(tool_names)} 个工具 · {write_mode}"
+    )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_arg_parser(include_selfcheck=True).parse_args(argv)
+    source = build_source(args)
+
+    from mcp.server.fastmcp import FastMCP
+
+    from .tools import register_tools
+
+    mcp = FastMCP("loomnote")
+    tool_names = register_tools(mcp, source, allow_publish_writes=args.allow_publish_writes)
+
+    if args.selfcheck:
+        sys.exit(_selfcheck(args, source, tool_names))
+
+    mcp.run(transport=args.transport)
+
+
+if __name__ == "__main__":
+    main()

loomnote_mcp/receipts_store.py

@@ -0,0 +1,93 @@
+"""publish-receipts store, abstracted over a document read/write callback pair
+instead of a filesystem path — same schema (v2), same validation/dedup/cap
+rules as `publish_receipts.py`, reused from there rather than re-implemented.
+
+`publish_receipts.py`'s own path-based load/append/list_for_note/update stay
+untouched (their 14 existing tests keep passing unmodified); this module is
+the COS/S3-friendly sibling used via NoteSource.read_document/write_document.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Callable, Optional
+
+import publish_receipts as pr
+
+DocumentReader = Callable[[str], Optional[str]]
+DocumentWriter = Callable[[str, str], None]
+
+DEFAULT_DOC_PATH = pr.STORE_FILENAME
+
+
+def load(read_document: DocumentReader, doc_path: str = DEFAULT_DOC_PATH) -> list[dict]:
+    text = read_document(doc_path)
+    if text is None:
+        return []
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return []
+    if not isinstance(data, dict) or not isinstance(data.get("receipts"), list):
+        return []
+    normalized = [pr.normalize_receipt(r) for r in data["receipts"] if isinstance(r, dict)]
+    return pr._dedupe_and_cap([r for r in normalized if r is not None])
+
+
+def append(
+    read_document: DocumentReader,
+    write_document: DocumentWriter,
+    seed: dict,
+    doc_path: str = DEFAULT_DOC_PATH,
+) -> dict:
+    """Validate, dedup, persist. Raises ValueError on invalid seed."""
+    receipt = pr.normalize_receipt(seed)
+    if receipt is None:
+        raise ValueError("invalid receipt: channel/status 非法或字段超长")
+    receipts = load(read_document, doc_path)
+    receipts.append(receipt)
+    receipts = pr._dedupe_and_cap(receipts)
+    _write(write_document, doc_path, receipts)
+    return receipt
+
+
+def list_for_note(
+    read_document: DocumentReader,
+    note_id: str,
+    current_body: str | None = None,
+    doc_path: str = DEFAULT_DOC_PATH,
+) -> list[dict]:
+    """Receipts for one note, newest first. Pass current_body to add a derived `stale` flag."""
+    rows = [r for r in load(read_document, doc_path) if r["note_id"] == note_id]
+    if current_body is None:
+        return rows
+    return [{**r, "stale": pr.is_stale(r, current_body)} for r in rows]
+
+
+def update(
+    read_document: DocumentReader,
+    write_document: DocumentWriter,
+    receipt_id: str,
+    patch: dict,
+    doc_path: str = DEFAULT_DOC_PATH,
+) -> dict:
+    """Merge patch into an existing receipt. Raises KeyError if the id is
+    unknown, ValueError if the merged receipt is invalid."""
+    if not isinstance(patch, dict):
+        raise ValueError("patch must be an object")
+    receipts = load(read_document, doc_path)
+    for i, r in enumerate(receipts):
+        if r["receipt_id"] == receipt_id:
+            merged = {**r, **{k: v for k, v in patch.items() if k not in pr._IMMUTABLE}}
+            updated = pr.normalize_receipt(merged)
+            if updated is None:
+                raise ValueError("invalid patch: channel/status 非法或字段超长")
+            receipts[i] = updated
+            _write(write_document, doc_path, pr._dedupe_and_cap(receipts))
+            return updated
+    raise KeyError(receipt_id)
+
+
+def _write(write_document: DocumentWriter, doc_path: str, receipts: list[dict]) -> None:
+    payload = {"version": pr.VERSION, "receipts": receipts}
+    write_document(doc_path, json.dumps(payload, ensure_ascii=False, indent=2))

loomnote_mcp/sources/__init__.py

@@ -0,0 +1 @@
+"""NoteSource implementations: disk (today's behavior) and COS/S3 (object store)."""

loomnote_mcp/sources/base.py

@@ -0,0 +1,60 @@
+"""NoteSource: the storage-agnostic interface every backend implements.
+
+Three operations are enough to build all 11 MCP tools on top of: list every
+note, read any root-relative document (memos/, but also publish-receipts.json
+and templates/wechat/*.json — same key layout the web app's
+S3Adapter/S3DocumentStore use, see web/src/adapter/s3/s3Documents.ts), and
+write — but writing is deliberately not "arbitrary": loomnote-mcp is started
+by the user's own AI client with the user's own storage credentials, so an
+untrusted or careless LLM must not be able to touch note content. See
+check_writable() below, which both DiskSource and CosSource call before ever
+touching storage.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Protocol, runtime_checkable
+
+# The ONLY document loomnote-mcp is ever allowed to write. Every write tool
+# (record_publish_receipt / publish_note / update_publish_receipt) ultimately
+# goes through receipts_store, which always targets this exact filename
+# (publish_receipts.STORE_FILENAME) — so this whitelist costs nothing in
+# functionality and closes off everything else: notes, images, templates,
+# config. Enforced here at the NoteSource boundary rather than trusted to
+# callers, so a bug in a tool (or a future tool nobody reviewed) can't widen
+# what gets written.
+WRITABLE_DOCUMENTS = frozenset({"publish-receipts.json"})
+
+# Checked, and rejected, before the WRITABLE_DOCUMENTS membership check even
+# runs — so these stay hard-denied even if WRITABLE_DOCUMENTS is ever widened
+# by mistake.
+_FORBIDDEN_WRITE_PREFIXES = ("memos/", "file/", "templates/")
+_FORBIDDEN_WRITE_EXACT = frozenset({".config.json"})
+
+_PERMISSION_MESSAGE = "loomnote-mcp 只允许写回执文件（publish-receipts.json）"
+
+
+def check_writable(path: str) -> None:
+    """Raise PermissionError unless `path` is the one document loomnote-mcp
+    may write. Call this first thing in every NoteSource.write_document."""
+    if path in _FORBIDDEN_WRITE_EXACT or path.startswith(_FORBIDDEN_WRITE_PREFIXES):
+        raise PermissionError(_PERMISSION_MESSAGE)
+    if path not in WRITABLE_DOCUMENTS:
+        raise PermissionError(_PERMISSION_MESSAGE)
+
+
+@runtime_checkable
+class NoteSource(Protocol):
+    def load_notes(self) -> list[dict]:
+        """All notes as {id, created, tags, body}, newest first by `created`."""
+        ...
+
+    def read_document(self, path: str) -> Optional[str]:
+        """Read one root-relative document (e.g. 'publish-receipts.json',
+        'memos/2026-09-02-1000.md'). Returns None if it doesn't exist."""
+        ...
+
+    def write_document(self, path: str, text: str) -> None:
+        """Write (create or replace) publish-receipts.json — the only path
+        check_writable() allows. Raises PermissionError for anything else."""
+        ...

loomnote_mcp/sources/cos.py

@@ -0,0 +1,134 @@
+"""COS/S3 NoteSource: reads memos/ and documents directly from an S3-API
+object store (Tencent COS, or plain AWS S3 / any S3-compatible endpoint).
+
+Everything is read into memory and returned; nothing is cached to local disk.
+Credentials are never handled here — the caller (cli.py) builds the boto3
+client from environment variables and hands it in, so this module has no
+notion of "secret" at all.
+
+Key layout matches the web app's S3Adapter (web/src/adapter/s3/*.ts):
+  <prefix>memos/<name>.md, <prefix>publish-receipts.json, <prefix>templates/...
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import notes_core
+
+from .base import check_writable
+
+_MEMOS_PREFIX = "memos/"
+_NOT_FOUND_CODES = {"NoSuchKey", "404", "NotFound"}
+
+
+def normalize_prefix(prefix: str) -> str:
+    prefix = (prefix or "").strip().strip("/")
+    return f"{prefix}/" if prefix else ""
+
+
+def cos_endpoint(region: str) -> str:
+    """Same formula as web/src/adapter/s3/paths.ts:cosEndpoint (no override)."""
+    return f"https://cos.{region}.myqcloud.com"
+
+
+def build_client(
+    *,
+    region: Optional[str],
+    endpoint: Optional[str],
+    access_key_id: str,
+    secret_access_key: str,
+):
+    """Build the boto3 S3 client. Split out from CosSource so tests can stub
+    the client directly without importing/network-hitting boto3."""
+    import boto3
+
+    endpoint_url = endpoint or (cos_endpoint(region) if region else None)
+    if not endpoint_url:
+        raise ValueError("需要 --region（COS）或 --endpoint（S3 兼容存储）")
+    return boto3.client(
+        "s3",
+        endpoint_url=endpoint_url,
+        region_name=region or "us-east-1",
+        aws_access_key_id=access_key_id,
+        aws_secret_access_key=secret_access_key,
+    )
+
+
+class CosSource:
+    """NoteSource backed by an S3-compatible bucket. `client` is any object
+    exposing boto3's S3 client surface (list_objects_v2/get_object/put_object).
+
+    Deliberately no delete_object call anywhere in this class, and no
+    delete_document on NoteSource at all: loomnote-mcp only ever needs to
+    append/update entries in publish-receipts.json (see write_document /
+    check_writable), never to remove an object from the bucket, so there is
+    no code path — and no tool — that can delete a note, an image, or
+    anything else the user stored.
+    """
+
+    def __init__(self, client: Any, bucket: str, prefix: str = ""):
+        self._client = client
+        self._bucket = bucket
+        self._prefix = normalize_prefix(prefix)
+
+    def load_notes(self) -> list[dict]:
+        notes = []
+        list_prefix = self._key(_MEMOS_PREFIX)
+        for key in self._list_keys(list_prefix):
+            if not key.endswith(".md"):
+                continue
+            text = self._get_text(key)
+            if text is None:
+                continue
+            note_id = key[len(self._prefix):]
+            tags, created, body = notes_core.parse(text)
+            notes.append({"id": note_id, "created": created, "tags": tags, "body": body})
+        notes.sort(key=lambda m: m["created"], reverse=True)
+        return notes
+
+    def read_document(self, path: str) -> str | None:
+        return self._get_text(self._key(path))
+
+    def write_document(self, path: str, text: str) -> None:
+        check_writable(path)
+        self._client.put_object(
+            Bucket=self._bucket,
+            Key=self._key(path),
+            Body=text.encode("utf-8"),
+            ContentType="application/octet-stream",
+        )
+
+    def _key(self, path: str) -> str:
+        return f"{self._prefix}{path}"
+
+    def _list_keys(self, prefix: str) -> list[str]:
+        keys: list[str] = []
+        token: str | None = None
+        while True:
+            kwargs: dict[str, Any] = {"Bucket": self._bucket, "Prefix": prefix}
+            if token:
+                kwargs["ContinuationToken"] = token
+            resp = self._client.list_objects_v2(**kwargs)
+            keys.extend(obj["Key"] for obj in resp.get("Contents", []))
+            if not resp.get("IsTruncated"):
+                break
+            token = resp.get("NextContinuationToken")
+        return keys
+
+    def _get_text(self, key: str) -> str | None:
+        try:
+            resp = self._client.get_object(Bucket=self._bucket, Key=key)
+        except Exception as exc:
+            if _is_not_found(exc):
+                return None
+            raise
+        body = resp["Body"]
+        data = body.read() if hasattr(body, "read") else body
+        return data.decode("utf-8") if isinstance(data, bytes) else str(data)
+
+
+def _is_not_found(exc: Exception) -> bool:
+    response = getattr(exc, "response", None)
+    code = response.get("Error", {}).get("Code") if isinstance(response, dict) else None
+    return (code or type(exc).__name__) in _NOT_FOUND_CODES

loomnote_mcp/sources/disk.py

@@ -0,0 +1,58 @@
+"""Disk NoteSource: today's mcp_server.py behavior, generalized to arbitrary
+root-relative documents (not just memos/*.md).
+
+`root` is the parent of the memos directory — the same directory that holds
+publish-receipts.json and .config.json in the disk layout, so `read_document` /
+`write_document` on e.g. "publish-receipts.json" or "memos/x.md" resolve the
+same way `notes_core.read_one` already does for notes.
+"""
+
+from __future__ import annotations
+
+import os
+
+import notes_core
+
+from .base import check_writable
+
+
+class DiskSource:
+    def __init__(self, notes_dir: str):
+        self.notes_dir = os.path.abspath(os.path.expanduser(notes_dir))
+        self.root = os.path.dirname(self.notes_dir)
+
+    def load_notes(self) -> list[dict]:
+        return notes_core.load(self.notes_dir)
+
+    def read_document(self, path: str) -> str | None:
+        fp = self._resolve(path)
+        if fp is None or not os.path.isfile(fp):
+            return None
+        with open(fp, encoding="utf-8") as f:
+            return f.read()
+
+    def write_document(self, path: str, text: str) -> None:
+        check_writable(path)
+        fp = self._resolve(path)
+        if fp is None:
+            raise ValueError(f"invalid document path: {path!r}")
+        parent = os.path.dirname(fp)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        tmp = fp + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as f:
+            f.write(text)
+        os.replace(tmp, fp)
+
+    def _resolve(self, path: str) -> str | None:
+        """Root-relative path -> absolute path, or None if it escapes root
+        (leading '/', '..' segment, or a symlink that resolves outside root)."""
+        if not path or path.startswith("/") or ".." in path.split("/"):
+            return None
+        fp = os.path.normpath(os.path.join(self.root, path))
+        if fp == self.root or not fp.startswith(self.root + os.sep):
+            return None
+        real_root = os.path.realpath(self.root)
+        if not (os.path.realpath(fp) + os.sep).startswith(real_root + os.sep):
+            return None
+        return fp