内容
# NotedThat
一个以 Markdown 为优先的知识库系统，通过 HTTP API、MCP 服务器和 WebDAV 端点暴露。NotedThat 将笔记存储为纯 Markdown 文件，通过 Qdrant 进行语义搜索索引，并通过多个访问协议显示，以便编辑器、AI 代理和 WebDAV 客户端可以处理相同的内容。
> **状态：预 v1** — 正在积极开发中。API 和 crate 接口不稳定。
## 文档
- [规格说明书.md](规格说明书.md) — 完整的产品和架构规格说明书
- [开发指南.md](开发指南.md) — 开发者命令和测试约定
- [发布指南.md](发布指南.md) — 发布操作手册和受信任的发布设置
- [许可证](许可证) — Mozilla 公共许可证 2.0
## Crate 映射
| Crate | 路径 | 角色 |
| ----- | ---- | ---- |
| `notedthat-core` | `crates/notedthat-core` | 共享域类型、路径/范围/错误/身份验证原语、配置 |
| `notedthat-storage-s3` | `crates/notedthat-storage-s3` | S3 存储适配器 |
| `notedthat-indexer` | `crates/notedthat-indexer` | 分块、嵌入客户端、Qdrant 集成 |
| `notedthat-write` | `crates/notedthat-write` | 共享写入路径（`commit()`、`commit_delete()`、MIME 类型嗅探、5 GiB 限制）— 用于 HTTP API + WebDAV 接口 |
| `notedthat-api-http` | `crates/notedthat-api-http` | HTTP API 接口 |
| `notedthat-webdav` | `crates/notedthat-webdav` | WebDAV 接口 |
| `notedthat-mcp` | `crates/notedthat-mcp` | MCP 工具模式和 HTTP 支持的实现 |
| `notedthat-server` | `crates/notedthat-server` | 主服务器二进制文件 — HTTP API + WebDAV + 远程 MCP 在一个进程中（发布 facade）。发布到 `ghcr.io/notedthat/server` 每个标记版本。 |
| `notedthat-mcp-stdio` | `crates/notedthat-mcp-stdio` | MCP-over-stdio 传输适配器 |
所有 9 个 crates 通过生态系统级别的语义版本控制共享一个版本。有关版本控制策略，请参见 [发布指南.md](发布指南.md)。
## 本地运行
NotedThat 需要一个 S3 兼容的对象存储。对于本地开发，我们使用 Docker 中的 [SeaweedFS](https://github.com/seaweedfs/seaweedfs) >= 4.18。
```sh
# 1. 在 S3 网关端口（8333）启动 SeaweedFS
docker run -d --name nt-seaweedfs \
-p 8333:8333 \
chrislusf/seaweedfs:4.18 server -s3 -filer
# 2. 启动 NotedThat 服务器
NOTEDTHAT_API_TOKEN=dev-token \
NOTEDTHAT_KBS=notes,scratch \
NOTEDTHAT_S3_ENDPOINT_URL=http://127.0.0.1:8333 \
NOTEDTHAT_S3_REGION=us-east-1 \
NOTEDTHAT_S3_ACCESS_KEY_ID=any \
NOTEDTHAT_S3_SECRET_ACCESS_KEY=any \
NOTEDTHAT_S3_FORCE_PATH_STYLE=true \
NOTEDTHAT_LISTEN_ADDR=127.0.0.1:8080 \
RUST_LOG=info,notedthat=debug \
cargo run -p notedthat-server
# 3. 验证服务器正在运行
curl http://127.0.0.1:8080/healthz
# 4. 尝试 API
curl -H "Authorization: Bearer dev-token" \
http://127.0.0.1:8080/v1/knowledgebases
# 5. 上传文件
echo "# Hello World" | curl -X PUT \
-H "Authorization: Bearer dev-token" \
-H "Content-Type: text/markdown" \
--data-binary @- \
http://127.0.0.1:8080/v1/knowledgebases/notes/hello.md
# 6. 读取它
curl -H "Authorization: Bearer dev-token" \
http://127.0.0.1:8080/v1/knowledgebases/notes/hello.md
```
### Docker（预构建镜像）
一旦存在第一个标记版本，服务器镜像将发布到 GHCR，地址为 `ghcr.io/notedthat/server`。每个发布的镜像都经过 cosign 签名（通过 Sigstore/Fulcio 无密钥）和 SLSA L2 构建溯源证明。
```sh
docker pull ghcr.io/notedthat/server:latest
docker run --rm -p 8080:8080 -p 8081:8081 \
-e NOTEDTHAT_API_TOKEN=dev-token \
-e NOTEDTHAT_KBS=notes,scratch \
-e NOTEDTHAT_S3_ENDPOINT_URL=http://host.docker.internal:8333 \
-e NOTEDTHAT_S3_REGION=us-east-1 \
-e NOTEDTHAT_S3_ACCESS_KEY_ID=any \
-e NOTEDTHAT_S3_SECRET_ACCESS_KEY=any \
ghcr.io/notedthat/server:latest
```
或者，使用捆绑的 [docker-compose.yml](docker-compose.yml) 使用 `docker compose up` 来获取完整的本地栈（SeaweedFS + Qdrant + 服务器）。
在生产环境中运行前，请验证签名 + 溯源：
```sh
gh attestation verify oci://ghcr.io/notedthat/server:0.2.0 --owner NotedThat
```
### WebDAV
服务器运行时（上述步骤 1-2），还需设置 WebDAV 凭证：
```sh
export NOTEDTHAT_WEBDAV_USERNAME=webdav-user-please-change
export NOTEDTHAT_WEBDAV_PASSWORD=webdav-pass-please-change
```
```sh
# 7. PROPFIND 根目录（列出 KB）
curl -X PROPFIND -u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
-H 'Depth: 1' http://127.0.0.1:8081/
# 8. 通过 WebDAV 上传 Markdown 文件
echo "# Hello WebDAV" | curl -X PUT \
-u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
--data-binary @- \
http://127.0.0.1:8081/notes/hello-webdav.md
# 9. 读取它
curl -u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
http://127.0.0.1:8081/notes/hello-webdav.md
# 10. 删除它
curl -X DELETE -u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
http://127.0.0.1:8081/notes/hello-webdav.md
```
### MCP（Claude Desktop，Cursor，Zed）
服务器运行时（上述步骤 1-2），配置您的 MCP 客户端以启动 `notedthat-mcp-stdio` 作为子进程。
#### 远程 MCP 主机
NotedThat 还为支持 MCP HTTP 传输的远程客户端公开了一个 HTTP MCP 端点：
- **端点**：`POST /mcp` 在端口 8082（可通过 `NOTEDTHAT_MCP_HTTP_BIND` 配置）
- **身份验证**：`Authorization: Bearer <NOTEDTHAT_API_TOKEN>`（与 HTTP API 相同的令牌）
- **注意**：公共部署需要 HTTPS 终止在反向代理之前，然后再公开此端口
参见 [`docs/API.md`](docs/API.md) 以获取完整的 MCP 传输和资源协议文档。
#### 安装选项
将 `notedthat-mcp-stdio` 安装到您的 `PATH` 中有三种方式 — 所有方式都等效，请根据您的设置选择适合的方式。安装程序脚本在第一个标记版本后可用。
**Shell 安装程序**（macOS / Linux）：
```sh
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/NotedThat/NotedThat/releases/latest/download/notedthat-mcp-stdio-installer.sh | sh
```
**PowerShell 安装程序**（Windows）：
```powershell
powershell -c "irm https://github.com/NotedThat/NotedThat/releases/latest/download/notedthat-mcp-stdio-installer.ps1 | iex"
```
**cargo 安装**（需要 Rust 工具链）：
```sh
cargo install notedthat-mcp-stdio
```
安装完成后，将其连接到您的 MCP 客户端：
```json
{
"mcpServers": {
"notedthat": {
"command": "notedthat-mcp-stdio",
"env": {
"NOTEDTHAT_URL": "http://localhost:8080",
"NOTEDTHAT_TOKEN": "your-token-here"
}
}
}
}
```
每个预构建的二进制文件都经过 cosign 签名，并带有 SLSA L2 构建溯源证明 — 在运行前验证：
```sh
cosign verify-blob \
--bundle notedthat-mcp-stdio.bundle \
--certificate-identity-regexp 'https://github.com/NotedThat/NotedThat/.+' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
notedthat-mcp-stdio
```
#### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"notedthat": {
"command": "notedthat-mcp-stdio",
"env": {
"NOTEDTHAT_URL": "http://localhost:8080",
"NOTEDTHAT_TOKEN": "your-token-here"
}
}
}
}
```
保存后重启 Claude Desktop。
#### Cursor
将以下内容添加到 Cursor 的设置中（`.cursor/mcp.json` 或通过设置 → MCP）：
```json
{
"mcpServers": {
"notedthat": {
"command": "notedthat-mcp-stdio",
"env": {
"NOTEDTHAT_URL": "http://localhost:8080",
"NOTEDTHAT_TOKEN": "your-token-here"
}
}
}
}
```
#### Zed
将以下内容添加到 Zed 设置中（`~/.config/zed/settings.json`）：
```json
{
"assistant": {
"mcp_servers": {
"notedthat": {
"command": {
"path": "notedthat-mcp-stdio",
"env": {
"NOTEDTHAT_URL": "http://localhost:8080",
"NOTEDTHAT_TOKEN": "your-token-here"
}
}
}
}
}
}
```
完整的环境变量参考：[`docs/CONFIGURATION.md`](docs/CONFIGURATION.md)
完整的 API 文档：[`docs/API.md`](docs/API.md)
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取贡献流程 — PR 工作流、提交约定（Conventional Commits + 签名 + DCO）、测试要求和 AI 辅助披露。构建、测试和运行命令位于 [DEVELOPMENT.md](DEVELOPMENT.md)。该项目为预 v1 版本，因此接口频繁更改 — 在开始重大工作前请检查开放问题。
## 许可证
Mozilla 公共许可证 2.0。有关完整文本，请参见 [LICENSE](LICENSE)。
