PinThePiece MCP server

PinThePiece MCP 服务

一个稳健的 Model Context Protocol（MCP）服务，提供先进的笔记管理系统。该服务实现了功能丰富的笔记存储解决方案，重点关注数据完整性、组织性和可访问性。主要功能包括分层存储、原子操作、版本控制支持、自动备份和全面的搜索能力。

功能

笔记存储系统

该服务实现了先进的笔记存储系统，具备以下功能：

• 分层存储结构，便于组织和扩展
• 原子文件操作，确保数据完整性
• 版本控制和元数据支持
• 自动备份
• 并发访问处理
• 全面的日志记录

存储结构

~/.pinthepiece/
├── notes/
│   ├── data/
│   │   └── YEAR/
│   │       └── MONTH/
│   │           └── note-name.json
│   ├── backups/
│   │   └── note-name.json.TIMESTAMP.bak
│   └── index.json
└── logs/
    └── notes.log

笔记格式

每条笔记都存储为 JSON 文件，包含：

• 内容：笔记的主要文本
• 创建／修改时间戳
• 用于组织的标签
• 描述（可选）
• 元数据，包括：
  • 格式版本
  • 上次备份时间戳
  • 内容校验和

资源

该服务实现了笔记存储系统，具备以下功能：

• 自定义 note:// URI 方案，用于访问单条笔记
• 每个笔记资源都包含：
  • 名称：唯一标识符
  • 内容：主要文本内容
  • 描述：可选描述
  • 标签：分类标签列表
  • 元数据：版本和完整性信息
  • MIME 类型：text/plain

数据安全功能

• 原子操作：所有文件写入均使用原子操作，防止数据损坏
• 备份系统：修改前自动备份
• 版本控制：对文件格式进行版本控制，以便未来兼容
• 数据验证：校验和验证及完整性检查
• 并发访问：使用文件锁确保线程安全
• 错误恢复：支持回滚的事务式操作

提示词

该服务提供一个提示词：

• summarize-notes：生成所有已存储笔记的摘要
  • 可选的“style”参数，用于控制详细程度（简洁／详细）
  • 生成的提示词会结合所有当前笔记和风格偏好

工具

该服务实现一个工具：

• add-note：向服务添加新笔记
  • 必需的字符串参数“name”和“content”
  • 可选参数“tags”和“description”
  • 更新服务状态，并通知客户端资源变更
  • 执行原子文件操作并创建备份

配置

存储位置

默认情况下，服务将笔记存储在：

• ~/.pinthepiece/notes/ - 主存储目录
• ~/.pinthepiece/logs/ - 日志文件

日志记录

• 详细记录所有操作
• 通过日志轮转管理磁盘空间
• 支持文件和控制台日志记录
• 日志级别可配置

快速入门

安装

Claude Desktop

MacOS 上：~/Library/Application\ Support/Claude/claude_desktop_config.json Windows 上：%APPDATA%/Claude/claude_desktop_config.json

开发中／未发布服务的配置

``` "mcpServers": { "pinthepiece": { "command": "uv", "args": [ "--directory", "/Users/pmoreira/create-python-server/pinthepiece", "run", "pinthepiece" ] } } ```

已发布服务的配置

``` "mcpServers": { "pinthepiece": { "command": "uvx", "args": [ "pinthepiece" ] } } ```

开发

构建和发布

准备分发软件包：

1. 同步依赖项并更新锁定文件：

uv sync

2. 构建软件包分发文件：

uv build

这将在 dist/ 目录中创建源代码分发包和 wheel 分发包。

3. 发布到 PyPI：

uv publish

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

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

调试

由于 MCP 服务通过 stdio 运行，调试可能颇具挑战。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP Inspector：

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

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL 开始调试。

错误处理

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

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