AI导哈

笔记管理系统

PinThePiece MCP server是一个功能丰富的笔记存储解决方案，专注于数据完整性、组织和可访问性，提供分层存储、原子操作、版本支持和自动备份等核心功能。

  • by psaboia
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 psaboia/PinThePiece

使用说明

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" ] } } ```

发展

建筑与出版

准备分发包裹：

  1. 同步依赖关系并更新锁文件：
uv sync
  1. 构建包分发：
uv build

这将在 dist/ 目录。

  1. 发布到PyPI：
uv publish

注意：您需要通过环境变量或命令标志设置PyPI凭据：

  • 令牌： --token 或 UV_PUBLISH_TOKEN
  • 或用户名/密码： --username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.

您可以通过以下方式启动MCP检查器 npm 使用此命令：

npx @modelcontextprotocol/inspector uv --directory /Users/pmoreira/create-python-server/pinthepiece run pinthepiece

启动后，检查器将显示一个URL，您可以在浏览器中访问该URL以开始调试。

错误处理

服务器实现了全面的错误处理：

  • 使用堆栈跟踪记录详细的错误
  • 自动清理临时文件
  • 从中断的操作中恢复
  • 备份恢复能力
  • 加载/保存时的数据验证

相关 MCP