Simplenote Mcp Server

Simplenote MCP 服务

一个轻量级 MCP 服务，使用 MCP Python SDK 将 Simplenote 与 Claude Desktop 集成。

这样，Claude Desktop 就可以将你的 Simplenote 笔记用作记忆后端或内容来源。

新增内容

30 个工具——完整兼容 Bear + Simplenote 差异化功能 + Claude 配套工具 + Vault 加密

Vault——可选的客户端笔记加密：Simplenote 不支持静态数据加密。现在，create_note/update_note 可接受 encrypt: true，encrypt_note/decrypt_note 可转换现有笔记——笔记正文在到达 Simplenote API 之前就会变成 AES-256-GCM 密文。请参阅 docs/security/encryption-design.md。

针对工作记忆助手用例，强化了 MCP Resources 和 Prompts：

• 修复：list_resources/read_resource 原本会通过非 schema 字段静默丢弃标签、日期和分页元数据；现在通过 MCP 规范的 _meta 扩展字段附加元数据，这是正确的机制。
• session-handoff MCP 提示词：为 Session Continuity 工作流搭建脚手架（使用 get_or_create_note + add_text，并采用 Status:/Next:/Blockers: 格式），以便在不同会话间交接上下文。

带有强制安全防护的不可逆删除工具：

• permanent_delete_note：永久销毁单条笔记；要求 confirm=true；默认先进行试运行预览
• empty_trash：永久删除所有已丢弃的笔记；默认 dry_run=true（预览）；要求同时设置 dry_run=false 和 confirm=true
• 1334 项测试通过，覆盖率 79% 以上，零 lint/type 错误

完整详情请参阅 CHANGELOG 和 ROADMAP.md。

v1.17.0

• search_notes 异步修复：布尔 AND 查询不再导致服务挂起；搜索现在通过线程池执行器运行，并设置 30 s 超时
• 子串预筛选：搜索 "test" 现在会正确返回包含 "testing"、"tested" 等内容的笔记
• 新增真实引擎集成测试套件；修复测试辅助工具中的导入错误

v1.16.0

• publish_note：将笔记发布到公开 URL——这是 Simplenote MCP 独有的功能；返回 public_url
• unpublish_note：取消笔记的公开访问；如果笔记已经取消发布，则不执行任何操作

完整详情请参阅 CHANGELOG。

---

🔧 功能

• 📝 完整的笔记管理：读取、创建、更新和删除 Simplenote 笔记
• 🔍 高级搜索：布尔运算符、短语匹配、标签和日期筛选
• ⚡ 高性能：内存缓存与后台同步
• 🔐 安全身份验证：通过环境变量进行基于令牌的身份验证
• 🔑 Vault 加密：可选的客户端 AES-256-GCM 加密，用于保护敏感笔记——Simplenote 本身不支持静态数据加密
• 🧩 兼容 MCP：可与 Claude Desktop 和其他 MCP 客户端配合使用
• 🐳 Docker 就绪：完整容器化，采用多阶段构建和安全强化
• 📊 监控：提供可选的 HTTP 端点，用于健康状态、就绪状态和指标监控
• 🧪 可靠的测试：全面的测试套件，包含 1334 项测试和持续集成
• 🔒 强化安全性：定期使用 Bandit、pip-audit 和依赖项检查进行安全扫描

---

🚀 快速开始

前提条件

• Simplenote 账号（在 simplenote.com 创建）
• Python 3.10+（非 Docker 安装时）或 Docker

选项 1：Docker（推荐）

最快的入门方式是使用我们预构建的 Docker 镜像：

# Pull and run the latest image
docker run -d \
  --name simplenote-mcp \
  -e [email protected] \
  -e SIMPLENOTE_PASSWORD=your-password \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
  -p 8000:8000 \
  docdyhr/simplenote-mcp-server:latest

只要 MCP_HTTP_HOST 不是 127.0.0.1/localhost，就必须设置 MCP_HTTP_AUTH_TOKEN，否则服务会拒绝启动（请参阅下文的“安全性”部分）。如果未设置 MCP_TRANSPORT=http，服务默认通过 stdio 运行，发布的端口上不会有任何监听。

Docker 健康检查： 健康监控使用的 HTTP 端点与上方的 MCP 协议端口是分开的，默认关闭，必须通过 -e ENABLE_HTTP_ENDPOINT=true -e HTTP_HOST=0.0.0.0 -p 8080:8080 显式启用（Docker 的 -p 映射会转发到容器的网络接口，而非其回环接口，因此必须将 HTTP_HOST 设为 0.0.0.0，发布的端口才能实际访问该端点——默认值 127.0.0.1 仅在你从同一容器内的其他进程调用这些端点时有效）：

• 健康状态：http://localhost:8080/health
• 就绪状态：http://localhost:8080/ready
• 指标：http://localhost:8080/metrics（Prometheus 格式）

如果 HTTP_HOST 绑定到非回环地址，却未设置 HTTP_ENDPOINT_AUTH_TOKEN，服务会拒绝启动，因为否则任何能够访问该端口的人都可以访问这些端点。如果需要绑定到非回环地址，请设置 Bearer 令牌（通过 Authorization: Bearer <token> 校验，与上文的 MCP_HTTP_AUTH_TOKEN 使用相同机制）——无论如何，回环地址的调用方始终受信任，因此这不会影响本地健康检查。尽可能仅绑定到回环地址，并使用 -p 127.0.0.1:8080:8080 发布端口，而非 -p 8080:8080。

也可以使用 Docker Compose：

# Clone the repository for docker-compose.yml
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server

# Set environment variables
export [email protected]
export SIMPLENOTE_PASSWORD=your-password

# Run with Docker Compose
docker-compose up -d

选项 2：Smithery（一键安装）

通过 Smithery 自动安装：

npx -y @smithery/cli install @docdyhr/simplenote-mcp-server --client claude

此方法会自动为 Claude Desktop 配置 MCP 服务。

选项 3：传统 Python 安装

git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e .
simplenote-mcp-server

---

🗂 文档索引与归档

• 请从 docs/DOCUMENTATION_GUIDE.md 开始，按指引浏览用户、开发者和运维文档及维护检查清单。
• 历史项目摘要现已归档在 docs/archive/2025/ 下，让仓库根目录专注于当前路线图和指南。
• 需要快速查找？运行 rg "<topic>" docs/，或前往 docs/index.md 查看 MkDocs 风格的目录。

---

🐳 Docker 部署

容器功能

• 多阶段构建，优化镜像大小
• 安全加固，使用非 root 用户并最大限度缩小攻击面
• 内置健康监控端点
• 资源限制和完善的信号处理
• 支持卷，用于持久化数据

使用预构建镜像

使用该服务最简单的方式是使用我们预构建的 Docker 镜像：

# Pull the latest image
docker pull docdyhr/simplenote-mcp-server:latest

# Run with Docker (see Quick Start above for the required MCP_HTTP_* env vars)
docker run -d \
  -e [email protected] \
  -e SIMPLENOTE_PASSWORD=your-password \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
  -p 8000:8000 \
  docdyhr/simplenote-mcp-server:latest

# Or use Docker Compose (set MCP_HTTP_AUTH_TOKEN in your environment/.env first)
docker-compose up -d

可用标签：

• latest - 最新稳定版本
• v1.18.3 - 指定版本
• main - 最新开发构建

生产部署

# Build and run the production container
docker-compose up -d

# Or build manually
docker build -t simplenote-mcp-server .
docker run -d \
  -e [email protected] \
  -e SIMPLENOTE_PASSWORD=your-password \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
  -p 8000:8000 \
  simplenote-mcp-server

使用 Docker 进行开发

# Use the development compose file for live code mounting
docker-compose -f docker-compose.dev.yml up

Docker 功能

• 多阶段构建，优化镜像大小（346MB）
• 多平台支持：linux/amd64 和 linux/arm64
• 安全加固：非 root 用户、只读文件系统、禁止提升权限
• 健康检查和自动重启策略
• 资源限制：1 个 CPU、512MB 内存
• 日志记录：持久化日志卷
• 基于环境变量的配置
• CI/CD 流水线：自动构建并发布到 Docker Hub
• 安全扫描：对所有镜像进行 Trivy 漏洞扫描
• 容器签名：使用 Sigstore cosign 签名保障供应链安全
• 适用于 Kubernetes：具备安全加固的生产级 Helm chart
• 自动更新：使用 Dependabot 管理依赖，并通过工作流自动更新版本
• 健康监控：持续健康检查和告警
• 企业通知：集成 Slack 和电子邮件，通知 CI/CD 状态

---

☸️ Kubernetes 部署

使用 Helm（推荐）

使用生产就绪的 Helm chart 部署到 Kubernetes：

# Install from local chart
helm install my-simplenote ./helm/simplenote-mcp-server \
  --set simplenote.email="[email protected]" \
  --set simplenote.password="your-password"

# Or with external secrets (recommended for production)
helm install my-simplenote ./helm/simplenote-mcp-server \
  --set externalSecrets.enabled=true \
  --set externalSecrets.secretStore.name="vault-backend"

Kubernetes 功能

• 安全强化：非 root 用户、只读文件系统、移除权限
• 资源管理：已配置 CPU／内存限制和请求
• 自动扩缩容：支持 Horizontal Pod Autoscaler
• 健康检查：存活和就绪探针
• 外部密钥：集成外部密钥管理
• 服务网格就绪：兼容 Istio 和其他服务网格

生产环境配置

# values.yaml for production
replicaCount: 3
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
resources:
  limits:
    cpu: 1000m
    memory: 512Mi
  requests:
    cpu: 500m
    memory: 256Mi

---

⚙️ 配置

环境变量

变量	必填	默认值	说明
SIMPLENOTE_EMAIL	是	-	Simplenote 账户邮箱
SIMPLENOTE_PASSWORD	是	-	Simplenote 账户密码
SYNC_INTERVAL_SECONDS	否	120	缓存同步间隔（秒）
CACHE_MAX_SIZE	否	10000	内存中保存的最大笔记数 — 设置为 ≥ 笔记总数
LOG_LEVEL	否	INFO	日志级别（DEBUG、INFO、WARNING、ERROR）
SIMPLENOTE_OFFLINE_MODE	否	false	跳过 API 调用；用于在没有凭据的情况下测试
MCP_TRANSPORT	否	stdio	stdio 或 http — MCP 协议传输方式
MCP_HTTP_HOST	否	127.0.0.1	MCP_TRANSPORT=http 时的绑定主机
MCP_HTTP_AUTH_TOKEN	有条件必填	-	Bearer 令牌；如果 MCP_HTTP_HOST 不是环回地址，则必填
MCP_HTTP_ALLOWED_HOSTS	否	-	以逗号分隔的允许列表，用于防范 DNS 重绑定攻击
MCP_HTTP_ALLOWED_ORIGINS	否	-	以逗号分隔的 Origin 允许列表（与上方选项配合使用）
ENABLE_HTTP_ENDPOINT	否	false	启用独立的 /health、/ready、/metrics 服务
HTTP_HOST	否	127.0.0.1	上述监控端点的绑定主机
HTTP_PORT	否	8080	上述监控端点的端口
HTTP_ENDPOINT_AUTH_TOKEN	有条件必填	-	Bearer 令牌；如果 HTTP_HOST 不是环回地址，则必填

Claude Desktop 集成

添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "simplenote": {
      "description": "Access and manage your Simplenote notes",
      "command": "simplenote-mcp-server",
      "env": {
        "SIMPLENOTE_EMAIL": "[email protected]",
        "SIMPLENOTE_PASSWORD": "your-password",
        "CACHE_MAX_SIZE": "10000"
      }
    }
  }
}

---

🔍 高级搜索

支持布尔逻辑和筛选条件的强大搜索功能：

# Boolean operators
project AND meeting AND NOT cancelled

# Phrase matching
"action items" AND project

# Tag filtering
meeting tag:work tag:important

# Date ranges
project from:2023-01-01 to:2023-12-31

# Combined query
"status update" AND project tag:work from:2023-01-01 NOT cancelled

---

🛠️ 可用工具

工具	描述	参数
create_note	创建新笔记	content、tags（可选）
update_note	替换笔记的全部内容（具有破坏性）	note_id、content、tags（可选）
delete_note	软删除：将笔记移至废纸篓	note_id
restore_note	从废纸篓恢复笔记	note_id
permanent_delete_note	永久销毁单条笔记（需要 confirm=true）	note_id、confirm
empty_trash	永久删除废纸篓中的所有笔记（默认先试运行）	dry_run（默认 true）、confirm（默认 false）
get_note	根据 ID 获取笔记及其完整内容和元数据	note_id
add_text	追加或前置文本，不覆盖现有内容	note_id、text、position（"end" | "beginning"）
search_notes	支持筛选和分页的全文搜索	query、limit、offset、tags、from_date、to_date、created_after、modified_after、pinned、fuzzy、sort_by
add_tags	为笔记添加标签	note_id、tags
remove_tags	从笔记中移除指定标签	note_id、tags
replace_tags	替换笔记的所有标签	note_id、tags
list_tags	列出所有标签及笔记数量	sort_by（"alpha" | "count"）
rename_tag	在所有笔记中原子性地重命名标签	old_tag、new_tag、dry_run（可选）
get_note_versions	列出笔记的版本历史	note_id
restore_version	将笔记回滚到先前版本	note_id、version_number
get_or_create_note	根据标题原子性地查找或创建笔记	title、tags（可选）、default_content（可选）
append_to_daily_note	向今日笔记追加带时间戳的条目	text、tags（可选）
replace_section	替换一个 Markdown 章节，不影响其他章节	note_id、header、content
find_untagged_notes	查找没有标签的笔记	limit（可选）
bulk_tag	一次调用为多条笔记添加标签	note_ids、tags
export_notes	将笔记导出为 Markdown 或 JSON	format、tags（可选）、query（可选）
find_and_merge_duplicates	检测并合并重复笔记	dry_run（可选）、similarity_threshold（可选）
get_server_info	服务版本、作者和运行时调试信息	（无参数）

---

📊 性能与缓存

• 内存缓存，并支持后台同步
• 分页支持，适用于大型笔记集合
• 标签和内容的索引查找
• 查询结果缓存，适用于重复搜索
• 优化 API 使用，最大限度减少 Simplenote 调用

---

🎯 近期改进

✅ 2025 年 1 月 - 性能与代码质量

关键错误修复：

• 修复 Claude Desktop 超时问题——将启动时间从 55+ 秒缩短至 < 1 秒（提升 98%）
• 为阻塞式 Simplenote API 调用实现线程池执行
• 通过后台加载，让缓存初始化真正实现非阻塞
• 解决关闭期间的 anyio.BrokenResourceError

代码重构 - 第一阶段已完成：

• 降低缓存模块复杂度：5 个高复杂度函数（CC >= 15）→ 0（降低 100%）
• 提升可维护性：缓存 MI 从 12.7 → 16.2（+28%）
• 提取 23 个辅助方法，让代码组织更清晰
• 670 项测试全部通过，同时保持 67% 的缓存覆盖率
• 详情请参阅 REFACTORING_PHASE1_COMPLETE.md

文档增强：

• 添加完整的 CHANGELOG.md，记录完整版本历史
• 创建 TESTING_CLAUDE_DESKTOP.md，作为用户测试指南
• 添加代码复杂度分析工具（check_complexity.py）
• 记录重构计划和完成报告

质量工具：

• 集成 Radon，用于自动化复杂度分析
• 基线指标：CC >= 15 的函数有 22 个（从 28 个减少）
• 平均可维护性指数：57.9（保持不变）
• 无诊断错误，所有质量门禁均通过

✅ 2025 年 9 月 - 质量与可靠性增强

✅ 质量与可靠性增强

测试套件稳定化：

• 修复导致间歇性失败的测试隔离问题
• 通过恰当的超时处理改进测试清理
• 改进夹具管理，提升测试可靠性
• 确保单独运行和套件运行时的测试结果一致

CI/CD 流水线优化：

• 将 28 个工作流整合为 16 个启用中的工作流
• 实现统一监控工作流，整合安全、健康状态和徽章检查
• 使用切实可行的 15.6% 基线改进测试覆盖率报告
• 增强 Docker 构建验证和安全扫描

代码质量改进：

• 所有 lint（Ruff）、格式检查和类型检查（MyPy）现已稳定通过
• 无高危安全漏洞（经 Bandit、pip-audit、safety 验证）
• 统一代码格式和 pre-commit hooks 配置
• 改进错误处理和面向用户的错误消息

🔧 开发者体验

改进测试：

• 724 项全面测试，覆盖核心功能
• 使用函数级夹具，提升测试隔离效果
• 建立切实可行的覆盖率基线（15.6%）
• 简化测试执行流程，并妥善清理

增强文档：

• 更新部署指南，纳入当前 Docker 配置
• 改进健康监控端点文档
• 添加常见问题的故障排查指南
• 补充当前状态和路线图文档

容器改进：

• 使用多阶段 Docker 构建，优化镜像大小
• 内置健康监控端点（/health、/ready、/metrics）
• 通过非 root 用户增强安全加固
• 改进信号处理和优雅关闭

---

🧪 测试与评估

MCP 评估 ✅

状态：✅ 正常运行 - 已完整集成 mcp-evals，并配备 TypeScript 封装程序！

本项目使用 mcp-evals 进行全面评估，以确保可靠性和性能：

# Setup evaluation environment
npm install
npm run validate:evals

# Run evaluation suites
npm run eval:smoke          # Quick smoke tests (2-3 minutes) ✅ VERIFIED
npm run eval:basic          # Standard evaluations (5-10 minutes)
npm run eval:comprehensive  # Full evaluation suite (15-30 minutes)

最新测试结果：5 项测试中有 4 项表现出色（平均 4.1/5）：

• 服务启动：4.6/5 ⭐（优秀）
• 身份验证：4.0/5 ⭐（良好）
• 笔记操作：3.8/5 ⭐（良好）
• 搜索：5.0/5 ⭐（完美）
• 错误处理：1.4/5 ⚠️（有待改进）

评估类型

• 冒烟测试：基本功能验证
• CRUD 操作：创建、读取、更新和删除笔记
• 搜索与筛选：布尔搜索、标签筛选、日期范围
• 错误处理：身份验证、网络问题、边缘情况
• 性能：大型数据集、并发操作
• 安全性：输入验证、强制身份验证

自动化测试

评估会在以下情况下自动运行：

• 拉取请求：冒烟测试 + 基本测试
• 发布：全面的评估套件
• 手动触发：包含详细报告的完整测试矩阵

评估使用 OpenAI 的 GPT 模型来评估：

• 准确性：响应的正确性
• 完整性：结果的全面程度
• 相关性：响应的适切性
• 清晰度：响应的可读性
• 性能：操作效率

📁 详细的评估文档请参阅 evals/README.md。

传统测试

# Python unit tests
pytest

# Code quality checks
ruff check .
mypy simplenote_mcp

---

🛡️ 安全性

• 通过环境变量进行基于令牌的身份验证
• Docker 镜像中没有硬编码凭据
• 使用非 root 用户的安全加固容器
• 生产容器中的只读文件系统
• 用于防止滥用的资源限制
• MCP HTTP 传输默认采用失败关闭策略：MCP_TRANSPORT=http 在 MCP_HTTP_HOST 为任何非回环地址时，如果未设置 MCP_HTTP_AUTH_TOKEN，则拒绝启动（这是一个共享的 Bearer 密钥，通过 恒定时间比较进行校验）。绑定到回环地址（127.0.0.1/localhost）时 无需令牌，与 stdio 的本地进程信任级别一致。设置 MCP_HTTP_ALLOWED_HOSTS/MCP_HTTP_ALLOWED_ORIGINS（逗号分隔）可为 非回环绑定启用 DNS 重绑定防护。此功能面向专用网络（位于 VPN/Tailscale/SSH 隧道之后）——静态 共享令牌不具备 OAuth 的撤销、审计和过期属性，因此即使设置了令牌， 也应避免将其直接暴露到公共互联网。

---

🚨 故障排除

常见问题

身份验证问题：

• 确认已正确设置 SIMPLENOTE_EMAIL 和 SIMPLENOTE_PASSWORD
• 检查凭据中是否有拼写错误

Docker 问题：

# Check container logs
docker-compose logs

# Restart services
docker-compose restart

# Rebuild if needed
docker-compose up --build

Claude Desktop 连接：

# Verify tools are available
./simplenote_mcp/scripts/verify_tools.sh

# Monitor logs
./simplenote_mcp/scripts/watch_logs.sh

诊断命令

# Test connectivity
python simplenote_mcp/tests/test_mcp_client.py

# Check server status
./simplenote_mcp/scripts/check_server_pid.sh

# Clean up and restart
./simplenote_mcp/scripts/cleanup_servers.sh

---

📚 开发

使用 mcp-evals 快速设置

# One-command setup including evaluations
./setup-dev-env-with-evals.sh

# Or manual setup
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e ".[dev,test]"
npm install  # For mcp-evals

本地开发

# Run the server
python simplenote_mcp_server.py

# Run Python tests
pytest

# Run mcp-evals
npm run eval:smoke    # Quick validation
npm run eval:basic    # Standard tests
npm run eval:all      # Full test suite

# Code quality
ruff check .
ruff format .
mypy simplenote_mcp

开发环境

设置脚本会创建：

• 包含所有依赖项的 Python 开发环境
• 用于 mcp-evals 的 Node.js 环境
• 示例配置文件
• 提交前钩子
• 所有评估文件的验证

测试策略

1. 单元测试：使用 Python pytest 测试核心逻辑
2. 集成测试：测试 MCP 协议合规性
3. 冒烟测试：快速验证基本功能
4. 评估测试：基于 LLM 评估实际使用情况
5. 性能测试：负载和压力测试

运行 MCP 评估

Docker 方式（推荐）

由于 tsx 可能存在权限问题，我们建议在 Docker 中运行 MCP 评估：

# Run smoke tests
./scripts/run-evals-docker.sh smoke

# Run basic evaluations
./scripts/run-evals-docker.sh basic

# Run comprehensive evaluations
./scripts/run-evals-docker.sh comprehensive

# Run all evaluations
./scripts/run-evals-docker.sh all

直接方式（如果权限允许）

npm run eval:smoke
npm run eval:basic
npm run eval:comprehensive
npm run eval:all

Docker 开发

# Development with live code reload
docker-compose -f docker-compose.dev.yml up

# Build and test
docker build -t simplenote-mcp-server:test .
docker run --rm simplenote-mcp-server:test --help

---

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING.md 了解指南。

📄 许可证

本项目采用 MIT 许可证——详情请参阅 LICENSE 文件。

🔗 相关项目

• Model Context Protocol
• MCP 示例服务

---

⭐ 支持此项目

如果您觉得此项目有用，请考虑在 GitHub 上点亮星标！您的支持有助于：

• 🚀 提高知名度，让更多可能受益于此工具的开发者发现它
• 💪 激励持续开发和维护
• 📈 围绕 Model Context Protocol 生态系统构建社区
• 🛡️ 通过社区参与建立信任

⭐ 为此代码库点亮星标 — 只需点击一次，却意义重大！

---