PinThePiece MCP服务器
一个强大的模型上下文协议（MCP）服务器，提供复杂的笔记管理系统。此服务器实现了一个功能丰富的笔记存储解决方案，重点是数据完整性、组织和可访问性。主要功能包括分层存储、原子操作、版本控制支持、自动备份和全面的搜索功能。
特性
纸币存储系统
服务器实现了一个复杂的纸币存储系统，具有：
- 分层存储结构，可实现更好的组织和可扩展性
- 数据完整性的原子文件操作
- 版本控制和元数据支持
- 自动备份
- 并发访问处理
- 综合录井
存储结构
~/.pinthepiece/
├── notes/
│ ├── data/
│ │ └── YEAR/
│ │ └── MONTH/
│ │ └── note-name.json
│ ├── backups/
│ │ └── note-name.json.TIMESTAMP.bak
│ └── index.json
└── logs/
└── notes.log备注格式
每个注释都存储为JSON文件，其中包含：
- 内容：说明正文
- 创建/修改时间戳
- 组织标签
- 说明（可选）
- 元数据包括：
- 格式版本 - 上次备份时间戳 - 内容校验和
资源
服务器实现了一个纸币存储系统，该系统具有：
- 自定义注释：//用于访问单个注释的URI方案
- 每个笔记资源都有：
- 名称：唯一标识符 - 内容：正文内容 - 描述：可选描述 - 标签：分类标签列表 - 元数据：版本和完整性信息 - MIME类型：text/plain
数据安全特性
- 原子操作：所有文件写入都使用原子操作来防止损坏
- 备份系统：修改前自动备份
- 版本控制：文件格式版本控制，以确保未来的兼容性
- 数据验证：校验和验证和完整性检查
- 并发访问：文件锁定以确保线程安全
- 错误恢复：具有回滚功能的事务类操作
鼓励
服务器提供一个提示：
- 总结笔记：创建所有存储笔记的摘要
- 可选的“style”参数，用于控制详细程度（简短/详细） - 生成将所有当前注释与样式首选项组合的提示
工具
服务器实现了一个工具：
- 添加注释：向服务器添加新注释
- 将“name”和“content”作为必需的字符串参数 - 可选的“标签”和“描述”参数 - 更新服务器状态并通知客户端资源更改 - 通过创建备份执行原子文件操作
配置
存储位置
默认情况下，服务器将注释存储在：
~/.pinthepiece/notes/-主存储目录~/.pinthepiece/logs/-日志文件
日志记录
- 所有操作的详细记录
- 空间管理日志轮换
- 文件和控制台日志都可用
- 可配置的日志级别
快速启动
安装
克劳德桌面
在MacOS上： ~/Library/Application\ Support/Claude/claude_desktop_config.json 在Windows上： %APPDATA%/Claude/claude_desktop_config.json
Development/Unpublished Servers Configuration
"mcpServers": {
"pinthepiece": {
"command": "uv",
"args": [
"--directory",
"/Users/pmoreira/create-python-server/pinthepiece",
"run",
"pinthepiece"
]
}
}Published Servers Configuration
"mcpServers": {
"pinthepiece": {
"command": "uvx",
"args": [
"pinthepiece"
]
}
}发展
建筑与出版
准备分发包裹：
- 同步依赖关系并更新锁文件：
uv sync- 构建包分发：
uv build这将在 dist/ 目录。
- 发布到PyPI：
uv publish注意：您需要通过环境变量或命令标志设置PyPI凭据：
- 令牌：
--token或UV_PUBLISH_TOKEN - 或用户名/密码：
--username/UV_PUBLISH_USERNAME和--password/UV_PUBLISH_PASSWORD
调试
由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.
您可以通过以下方式启动MCP检查器 使用此命令：
npx @modelcontextprotocol/inspector uv --directory /Users/pmoreira/create-python-server/pinthepiece run pinthepiece启动后，检查器将显示一个URL，您可以在浏览器中访问该URL以开始调试。
错误处理
服务器实现了全面的错误处理：
- 使用堆栈跟踪记录详细的错误
- 自动清理临时文件
- 从中断的操作中恢复
- 备份恢复能力
- 加载/保存时的数据验证
