Simplenote MCP Server

Simplenote MCP服务器

Simplenote MCP Server Logo

这允许Claude Desktop作为内存后端或内容源与您的Simplenote笔记进行交互。

 

](https://github.com/docdyhr/simplenote-mcp-server) ](./CHANGELOG.md)  

](https://pypi.org/project/simplenote-mcp-server/) ](https://hub.docker.com/r/docdyhr/simplenote-mcp-server) ](https://github.com/docdyhr/simplenote-mcp-server)

   


最新动态（未发布）

26个工具——全熊奇偶校验+单音符微分器+克劳德配套工具

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

• permanent_delete_note：永久销毁一张纸币；需要 confirm=true；默认情况下为模拟运行预览
• empty_trash：永久删除所有被丢弃的笔记；默认为 dry_run=true （预览）；需要 dry_run=false 与 confirm=true
• 1188项测试通过，覆盖率77%，零漏检/类型错误

v1.16.1

• search_notes 异步修复：布尔AND查询不再挂起服务器；搜索现在在线程池执行器中运行，超时30秒
• 变电站预过滤器：现在正确搜索“test”会返回包含“testing”、“tested”等的注释。
• 增加了真实的发动机集成测试套件；已修复测试帮助程序中的导入错误

v1.16.0

• publish_note：将注释发布到Simplenote MCP独有的公共URL；回报 public_url
• unpublish_note：从公共访问中删除注释；如果已未发布，则无操作

看 更新日志 了解完整细节。

看 更新日志 了解完整细节。

______________________________________________________________________

🔧 特性

• 📝 完整笔记管理：读取、创建、更新和删除Simplenote笔记
• 🔍 高级搜索：布尔运算符、短语匹配、标记和日期过滤器
• ⚡ 高性能：具有后台同步功能的内存缓存
• 🔐 安全认证：通过环境变量进行基于令牌的身份验证
• 🧩 MCP兼容：与Claude Desktop和其他MCP客户端配合使用
• 🐳 Docker就绪：全集装箱化，多阶段构建和安全强化
• 📊 监控：用于健康、准备和指标的可选HTTP端点
• 🧪 健壮性测试：包含1135+个测试和持续集成的全面测试套件
• 🔒 安全强化：使用Bandit、pip审计和依赖性检查进行定期安全扫描

______________________________________________________________________

🚀 快速开始

先决条件

• Simplenote帐户（在以下位置创建一个 simplenote.com)
• Python 3.10+（适用于非Docker安装）或Docker

选项1:Docker（推荐）

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

# Pull and run the latest image
docker run -d \
  --name simplenote-mcp \
  -e SIMPLENOTE_EMAIL=your.email@example.com \
  -e SIMPLENOTE_PASSWORD=your-password \
  -p 8000:8000 \
  docdyhr/simplenote-mcp-server:latest

Docker健康检查： 容器包括内置的健康监测端点：

• 健康： http://localhost:8000/health
• 准备就绪： http://localhost:8000/ready
• 韵律学： http://localhost:8000/metrics （普罗米修斯格式）

或者使用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 SIMPLENOTE_EMAIL=your.email@example.com
export SIMPLENOTE_PASSWORD=your-password

# Run with Docker Compose
docker-compose up -d

选项2: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 "" docs/ 或跳到 docs/index.md 用于MkDocs样式的目录。

______________________________________________________________________

🐳 Docker部署

集装箱特征

• 多阶段构建 用于优化图像大小
• 安全加固 非root用户和最小攻击面
• 健康监测 内置端点
• 资源限制 以及适当的信号处理
• 容量支持 用于持久数据

使用预构建图像

使用服务器最简单的方法是使用我们预先构建的Docker镜像：

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

# Run with Docker
docker run -d \
  -e SIMPLENOTE_EMAIL=your.email@example.com \
  -e SIMPLENOTE_PASSWORD=your-password \
  -p 8000:8000 \
  docdyhr/simplenote-mcp-server:latest

# Or use Docker Compose
docker-compose up -d

可用标签：

• latest -最新稳定版本
• v1.16.1 -具体版本
• main -最新开发版本

生产部署

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

# Or build manually
docker build -t simplenote-mcp-server .
docker run -d \
  -e SIMPLENOTE_EMAIL=your.email@example.com \
  -e SIMPLENOTE_PASSWORD=your-password \
  -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联合签名
• Kubernetes就绪：具有安全强化功能的生产级Helm chart
• 自动更新：Dependabot用于依赖关系、自动版本控制工作流
• 健康监测：持续的健康检查和警报
• 企业通知：用于CI/CD状态的Slack和电子邮件集成

______________________________________________________________________

☸️ Kubernetes部署

使用Helm（推荐）

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

# Install from local chart
helm install my-simplenote ./helm/simplenote-mcp-server \
  --set simplenote.email="your-email@example.com" \
  --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/内存限制和请求
• 自动缩放：水平Pod自动缩放支持
• 健康检查：活体和准备状态探测
• 外部秘密：与外部秘密管理集成
• 服务网格就绪：与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

______________________________________________________________________

⚙️ 配置

环境变量

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "simplenote": {
      "description": "Access and manage your Simplenote notes",
      "command": "simplenote-mcp-server",
      "env": {
        "SIMPLENOTE_EMAIL": "your.email@example.com",
        "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

______________________________________________________________________

🛠️ 可用工具

______________________________________________________________________

📊 性能和缓存

• 内存缓存 具有后台同步功能
• 分页支持 用于大额纸币收藏
• 索引查找 用于标签和内容
• 查询结果缓存 用于重复搜索
• 优化API使用 使用最少的Simplenote调用

______________________________________________________________________

🎯 最近的改进

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

关键Bug修复:

• 修复了Claude桌面超时问题 -启动时间从55+秒缩短到\=15）→ 0 （减少100%）
• 可维护性提高：从12.7开始缓存MI→ 16.2 (+28%)
• 提取23个辅助方法以更好地组织代码
• 所有670个测试均通过，缓存覆盖率保持在67%
• 看 REFACTORING_PHASE1_COMPLETE.md 详情

文档增强:

• 增加了全面 CHANGELOG.md 具有完整的版本历史记录
• 创建 TESTING_CLAUDE_DESKTOP.md 用户测试指南
• 添加了代码复杂性分析工具(check_complexity.py)
• 记录重构计划和完成报告

质量工具:

• 集成Radon用于自动化复杂性分析
• 基线指标：22个功能CC>=15（低于28个）
• 平均可维护性指数：57.9（已维护）
• 零诊断错误，所有质量门都通过

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

✅ 质量和可靠性增强

测试套件稳定性:

• 修复了导致间歇性故障的测试隔离问题
• 通过适当的超时处理改进了测试清理
• 增强夹具管理，提高测试可靠性
• 在单个和套件运行中实现了一致的测试结果

CI/CD流水线优化:

• 将28个工作流整合为16个活动工作流
• 实施了结合安全、健康和徽章检查的统一监控工作流程
• 改进了测试覆盖率报告，基线为15.6%
• 增强的Docker构建验证和安全扫描

代码质量改进:

• 所有linting（Ruff）、格式化和类型检查（MyPy）现在都一致通过
• 零高严重性安全漏洞（通过Bandit、pip审计、安全验证）
• 标准化的代码格式和预提交挂钩配置
• 增强的错误处理和面向用户的错误消息

🔧 开发者体验

改进测试:

• 724项涵盖核心功能的综合测试
• 功能范围的夹具，用于更好的测试隔离
• 建立了现实的覆盖基线（15.6%）
• 通过适当的清理简化测试执行

增强文档:

• 使用当前Docker设置更新部署指南
• 改进了健康监测端点文档
• 为常见问题添加了故障排除指南
• 当前状态和路线图文档

集装箱改进:

• 多阶段Docker构建，优化镜像大小
• 内置健康监测端点(/health, /ready, /metrics)
• 增强非root用户的安全强化
• 改进的信号处理和优雅的关机

______________________________________________________________________

🧪 测试与评估

MCP评估✅

状态: ✅ 工作中 -完成mcp评估与TypeScript包装器的集成！

该项目包括使用 mcp评估 为了确保可靠性和性能：

# 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)

最新测试结果：4/5测试通过（平均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用户
• 只读文件系统 在生产容器中
• 资源限制 防止滥用

______________________________________________________________________

🚨 故障排除

常见问题

身份验证问题:

• 验证 SIMPLENOTE_EMAIL 和 SIMPLENOTE_PASSWORD 设置正确
• 检查凭据中的拼写错误

Docker问题:

# Check container logs
docker-compose logs

# Restart services
docker-compose restart

# Rebuild if needed
docker-compose up --build

Claude桌面连接:

# 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

______________________________________________________________________

🤝 贡献

欢迎投稿！请阅读 贡献.md 作为指导方针。

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🔗 相关项目

• 模型上下文协议
• MCP示例服务器

______________________________________________________________________

⭐ 支持项目

如果你觉得这个项目很有帮助，请考虑在GitHub上给它一颗星！您的支持有助于：

• 🚀 提高能见度 对于可能从该工具中受益的其他开发人员
• 💪 激励持续发展 和维护
• 📈 建立社区 围绕模型上下文协议生态系统
• 🛡️ 验证信任 通过社区参与

](https://github.com/docdyhr/simplenote-mcp-server/stargazers)

⭐ 标记此存储库 --只需点击一下，就意味着很多！

______________________________________________________________________

](https://mseep.ai/app/docdyhr-simplenote-mcp-server)