简单笔记-mcp服务器

Name: 简单笔记-mcp服务器
Author: docdyhr

作者：docdyhr7 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Simplenote MCP Server

这是一个轻量级的MCP服务器，它通过MCP Python SDK将Simplenote与Claude Desktop集成在一起。

这使得Claude Desktop可以将Simplenote笔记作为记忆后端或内容源进行交互。

🎉 v1.9.0 新特性

重大性能突破 - 完全生产就绪！

版本1.9.0带来了98%的启动性能提升，标志着该项目已完全准备好用于Claude Desktop集成：

🚀 启动时间：从55秒以上减少到小于1秒（98%的改进）
✅ Claude Desktop就绪：修复了阻止MCP集成的关键超时问题
📊 代码质量：高复杂度函数减少了21%，第一阶段重构完成
📚 完整文档：全面指南、模板和生产验证
🎯 零技术债务：0个开放问题，0个开放PR，所有质量门都通过
🏆 A+健康状态：756个测试通过，69.64%的覆盖率，100%的CI成功率

关键改进：

使用线程池执行阻塞Simplenote API调用
实现真正的非阻塞缓存初始化和后台加载
启动期间优雅处理空缓存
增强监控和复杂性分析工具
GitHub问题模板以促进更好的社区参与

详细信息见CHANGELOG。

🔧 特性

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

🚀 快速开始

先决条件

Simplenote账户（在simplenote.com创建一个）
Python 3.10+（对于非Docker安装）或Docker

方案1：Docker（推荐）

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

# 拉取并运行最新镜像
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（Prometheus格式）

或者使用Docker Compose：

# 克隆仓库以获取docker-compose.yml
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server

# 设置环境变量
export SIMPLENOTE_EMAIL=your.email@example.com
export SIMPLENOTE_PASSWORD=your-password

# 使用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 "<主题>" docs/或跳转至docs/index.md查看MkDocs样式的目录。

🐳 Docker部署

容器特性

多阶段构建优化镜像大小
安全加固使用非root用户和最小攻击面
内置健康检查端点
资源限制和适当的信号处理
卷支持持久数据

使用预建镜像

最简单的方法是使用我们的预建Docker镜像：

# 拉取最新镜像
docker pull docdyhr/simplenote-mcp-server:latest

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

# 或者使用Docker Compose
docker-compose up -d

可用标签：

latest - 最新稳定发布版
v1.9.0 - 特定版本
main - 最新开发构建

生产部署

# 构建并运行生产容器
docker-compose up -d

# 或手动构建
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

# 使用开发compose文件进行实时代码挂载
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图表，带有安全加固
自动更新：Dependabot用于依赖项，自动版本工作流
健康监控：持续健康检查和警报
企业通知：Slack和电子邮件集成用于CI/CD状态

☸️ Kubernetes部署

使用Helm（推荐）

使用我们的生产级Helm图表部署到Kubernetes：

# 从本地图表安装
helm install my-simplenote ./helm/simplenote-mcp-server \
  --set simplenote.email="your-email@example.com" \
  --set simplenote.password="your-password"

# 或使用外部密钥（推荐用于生产）
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
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	缓存同步间隔
`LOG_LEVEL`	否	INFO	日志级别（DEBUG, INFO, WARNING, ERROR）

Claude Desktop集成

添加到您的claude_desktop_config.json：

{
  "mcpServers": {
    "simplenote": {
      "description": "访问和管理您的Simplenote笔记",
      "command": "simplenote-mcp-server",
      "env": {
        "SIMPLENOTE_EMAIL": "your.email@example.com",
        "SIMPLENOTE_PASSWORD": "your-password"
      }
    }
  }
}

🔍 高级搜索

强大的搜索功能，支持布尔逻辑和过滤器：

# 布尔运算符
project AND meeting AND NOT cancelled

# 短语匹配
"action items" AND project

# 标签过滤
meeting tag:work tag:important

# 日期范围
project from:2023-01-01 to:2023-12-31

# 组合查询
"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`
`get_note`	通过ID获取笔记	`note_id`
`search_notes`	带有筛选器的高级搜索	`query`, `limit`, `offset`, `tags`, `from_date`, `to_date`
`add_tags`	向笔记添加标签	`note_id`, `tags`
`remove_tags`	从笔记中移除标签	`note_id`, `tags`
`replace_tags`	替换笔记上的所有标签	`note_id`, `tags`

📊 性能与缓存

内存缓存与后台同步
分页支持大型笔记集合
索引查找标签和内容
查询结果缓存重复搜索
优化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进行自动复杂性分析
基准指标：22个函数CC >= 15（从28个下降）
平均可维护性指数：57.9（维持）
无诊断错误，所有质量门都通过

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

✅ 质量与可靠性增强

测试套件稳定化：

修复了导致间歇性失败的测试隔离问题
改进了具有适当超时处理的测试清理
增强了固定装置管理以提高测试可靠性
在单独和套件运行之间实现了一致的测试结果

CI/CD管道优化：

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

代码质量改进：

所有linting（Ruff）、格式化和类型检查（MyPy）现在一致通过
无高严重性的安全漏洞（通过Bandit、pip-audit、safety验证）
标准化了代码格式化和pre-commit钩子配置
增强了错误处理和面向用户的错误消息

🔧 开发者体验

改进测试：

包含核心功能的724个全面测试
函数作用域固定装置以实现更好的测试隔离
建立了现实的覆盖率基准（15.6%）
简化了具有适当清理的测试执行

增强文档：

更新了