笔记
MCP服务器，代理 应用程序表 应用 持有笔记，使用每个用户的JWT身份验证。通过stdio在本地工作 单用户和部署时作为多用户HTTP服务。列表、阅读、， 添加、更新注释并列出来自任何MCP客户端的附件。
建于 mcp应用程序.
安装
pipx install git+https://github.com/krisrowe/notes.git这将安装三个命令：
notes--shell快捷方式(list,read,add,update,attachments list)notes-mcp--MCP服务器(stdio,serve)notes-admin--管理员CLI(connect,users,tokens,health,probe,register)
先决条件：Python 3.10+，一个具有 预期模式.
在本地运行（stdio）
对于您自己机器上的单用户设置：注册 local 简介 持有AppSheet API密钥，然后将MCP客户端指向 notes-mcp stdio.
1.将本地用户添加到您的AppSheet目标中
notes-admin connect local
notes-admin users add local \
--datastore appsheet \
--app-id \
--api-key 这 datastore 字段选择后端实现。 appsheet 是目前唯一支持的值。未来版本可能会添加 其他（例如谷歌表格、firestore）。如果配置文件命名为 运行版本不知道的数据存储，SDK会引发 引用运行说明版本和支持的集合时出现明显错误。
这 app_id 和 api_key 一起定义哪个AppSheet应用程序 配置文件从读取。看 docs/APPSHEET.md 为了 在哪里可以找到两者。
如果您的AppSheet应用程序使用的表名不是 Note 和 Attachment，设置：
export APPSHEET_NOTE_TABLE=
export APPSHEET_ATTACHMENT_TABLE=2.向您的MCP客户注册
克劳德代码：
claude mcp add --scope user notes -- notes-mcp stdio --user localGemini CLI：
gemini mcp add notes --command notes-mcp --args "stdio --user local" --scope user3.烟雾测试
notes list --limit 3或者，在注册了stdio的情况下，询问MCP客户端：“列出我最近的笔记。”
部署（HTTP）
运行时合同
服务器是一个标准的ASGI Python应用程序，具有以下要求：
| Var | 必填 | 默认 | 用途 |
|---|---|---|---|
SIGNING_KEY | 是 | -- | JWT签名密钥。生成方式 python3 -c 'import secrets; print(secrets.token_urlsafe(32))' |
APP_USERS_PATH | 没有 | ~/.local/share/notes/users/ | 每个用户配置文件数据目录。 必须在无服务器平台上保持持久性 --默认为临时容器存储。 |
APPSHEET_NOTE_TABLE | 没有 | Note | 仅当您的AppSheet应用程序使用非默认笔记表名称时才覆盖 |
APPSHEET_ATTACHMENT_TABLE | 没有 | Attachment | 仅当您的AppSheet应用程序使用非默认附件表名时才覆盖 |
JWT_AUD | 否 | 未验证 | 预期JWT受众声明 |
TOKEN_DURATION_SECONDS | 否 | 315360000（~10y） | 新令牌生命周期（秒） |
应用程序表 app_id 和 api_key 它们不是环境变量——它们生活在 每个用户的个人资料（每个用户，可独立旋转）。请参阅“管理 用户”下面。
- 启动命令：
notes-mcp serve --host 0.0.0.0 --port $PORT - MCP端点：
/（根，不是/mcp) - 健康：
GET /health（无身份验证） - 管理员：
POST/GET/DELETE/PATCH /admin/...（签名密钥认证） - 身份验证模型： 该应用程序自行处理JWT身份验证；平台必须允许未经身份验证的流量通过应用程序——每个请求都由mcp-app的中间件进行门控。
SIGNING_KEY 这是一个秘密。通过平台的秘密管理器注入它 （GCP Secret Manager、AWS Secrets Manager、GitHub Actions Secrets等） --永远不要将其签入回购。
码头工人
docker build -t notes .
docker run -p 8080:8080 \
-e SIGNING_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))') \
-v /path/on/host:/data \
-e APP_USERS_PATH=/data/users \
notes程序文件感知平台（Heroku、Render、Fly、gcloud run-source）
一条线 Procfile 与回购一起发货：
web: notes-mcp serve --host 0.0.0.0 --port $PORT集 SIGNING_KEY 和一个持久 APP_USERS_PATH 穿过 平台的env-var或secret机制，然后从源代码部署。
部署后连接管理员CLI
管理员CLI根据以下应用程序配置进行持久化 ~/.config/notes/setup.json 因此后续命令不会重复 --url 或 --signing-key. connect 部署本身是独立的——部署不会自动连接 管理CLI。
notes-admin connect https:// --signing-key ` 无论价值如何 SIGNING_KEY` 在部署时设置为。 从部署存储秘密的任何位置（云）检索它 密钥管理器、CI/CD密钥、部署工具管理值）。
对于本地商店管理员（ local stdio模式下使用的配置文件）：
notes-admin connect local管理用户和凭据
每个授权用户都会获得一个存储的个人资料，其中包含他们的AppSheet 目标-- app_id 他们阅读的应用程序，以及 api_key 到 访问它：
notes-admin users add alice@example.com \
--datastore appsheet \
--app-id \
--api-key
notes-admin users list
notes-admin users get-profile alice@example.com旋转API键
users add 拒绝现有用户以防止意外覆盖。 使用 update-profile 要旋转任一字段：
notes-admin users update-profile alice@example.com api_key
notes-admin users update-profile alice@example.com app_id 发现配置文件字段
CLI是自文档化的-- --help 打印字段名称和 描述：
notes-admin users add --help撤销访问权限
notes-admin users revoke alice@example.com验证并注册MCP客户端
probe 是单端到端检查——确认服务器已启动， auth工作，MCP层使用预期的工具进行响应：
notes-admin probe为了更深入地检查用户的后端凭证， 运行安全工具-- count_notes 随着 limit=10，服务器端封顶：
notes-admin safe-tool --invoke --user alice@example.com退货 {"notes": {"found": N, "limit": 10}} 没有显示任何注释 内容。使用此选项确认已部署用户的后端是可访问的 并进行端到端的身份验证。
register 为用户生成一个令牌，并发出即贴注册 Claude Code、Gemini CLI和Claude.ai web客户端的命令：
notes-admin register --user alice@example.com手动注册，如果 register 不可用：
# Claude Code (HTTP transport)
claude mcp add --scope user notes-remote \
--transport http https:/// \
--header "Authorization: Bearer "
# Gemini CLI (HTTP transport)
gemini mcp add notes-remote https:/// \
--transport http \
--header "Authorization=Bearer " \
--scope user对于Claude.ai（网络），请使用URL https:/// 随着 用户令牌作为承载凭证。
MCP工具
| 工具 | 说明 |
|---|---|
list_notes | 使用Gmail风格的查询搜索/列出笔记 |
read_note | 按ID读取单个注释 |
add_note | 创建注释 |
update_note | 更新笔记的标题/内容/标签 |
list_attachments | 列出注释的附件 |
count_notes | 清点钞票（加盖）；只有身份，没有笔记内容。作为部署烟雾测试的两倍。 |
工具描述和参数模式来自文档字符串和 键入提示 notes/mcp/tools.py --这是典型的参考文献。
查询语法（list_notes）
| 查询 | 含义 |
|---|---|
meeting | 标题和内容中的文本搜索 |
"exact phrase" | 短语搜索 |
label:work | 按标签筛选 |
-label:archived | 排除标签 |
meeting label:work | 文本AND标签（隐式AND） |
label:work OR label:home | 任一标签 |
(label:a OR label:b) meeting | 用括号分组 |
Shell快捷方式（注意CLI）
这 notes 命令是shell中即席查询的精简包装器。 每个命令都会加载 local 来自商店的用户，除非 --user 是 通过。
notes list # All notes (default 50)
notes list "label:work" # Filter
notes list "meeting -label:archived" # Search + exclude
notes list --sort=-modified --limit 10 # Sort and limit
notes read # Read one note
notes add "Title" -c "Body" -l "Work" # Create
notes update -t "New title" # Update
notes attachments list # List attachments延伸阅读
- docs/APPSHEET.md --AppSheet凭据、表模式、故障排除
- 贡献.md --架构、测试、开发
许可证
麻省理工学院