Metadata-Version: 2.4
Name: loomnote-mcp
Version: 0.1.0
Summary: Loomnote MCP server: read notes and record multi-channel publish receipts from your own storage (disk, Tencent COS, or S3). / Loomnote 的 MCP 服务端：从你自己的存储（磁盘、腾讯云 COS 或 S3）读笔记、记发布回执。
Author: MyAgentHubs
License: MIT
Project-URL: Homepage, https://loomnote.myagenthubs.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.29
Requires-Dist: boto3>=1.34
Dynamic: license-file

# 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 接入」页会按你的实际存储配置生成这段
命令，直接复制粘贴，不用手拼。
