PinThePiece 笔记服务器使用说明

项目简介

PinThePiece 是一款基于 Model Context Protocol (MCP) 构建的笔记管理服务器。它提供了一个结构化的笔记存储系统，支持层级目录、原子操作、版本控制和自动备份等功能，确保您的笔记数据安全可靠。通过 MCP 协议，PinThePiece 可以与支持 MCP 协议的客户端（如 Claude Desktop）连接，让您在 LLM 应用中方便地访问和管理个人笔记。

主要功能点

笔记存储与管理: 提供层级结构的笔记存储，方便组织和查找笔记。支持创建、读取、更新和删除笔记操作。
数据安全特性: 采用原子操作、自动备份、版本控制和校验和验证等多种机制，保障数据完整性和安全性。
资源访问: 将每篇笔记作为资源进行管理，可以通过 'note://{note_name}' URI 访问特定笔记的内容。
工具调用: 提供 'add-note', 'get-note', 'update-note', 'delete-note', 'list-notes', 'search-notes' 等工具，方便客户端程序对笔记进行各种操作。
Prompt 模板: 内置 'summarize-notes' Prompt 模板，可以根据笔记内容生成摘要。

安装步骤

安装依赖: 确保您已安装 Python 运行环境，并使用 'uv sync' 命令同步项目依赖。
```
uv sync
```
构建: 运行 'uv build' 命令构建项目包。
```
uv build
```
这将在 'dist/' 目录生成软件包。
发布 (可选): 如果您希望将服务器发布到 PyPI，可以运行 'uv publish' 命令。但对于本地使用，此步骤通常不是必需的。
```
uv publish
```

服务器配置

为了让 MCP 客户端（例如 Claude Desktop）能够连接到 PinThePiece 服务器，您需要在客户端的配置文件中添加服务器配置信息。以下是针对 Claude Desktop 的配置示例，根据您的操作系统选择相应的配置文件路径进行修改：

MacOS: '~/Library/Application\ Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%/Claude/claude_desktop_config.json'

在配置文件的 '"mcpServers"' 字段中，添加如下 JSON 配置：

"mcpServers": {
  "pinthepiece": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/pinthepiece",  //  请替换为 PinThePiece 仓库的实际路径
      "run",
      "pinthepiece"
    ]
  }
}

配置参数说明:

'"pinthepiece"': 服务器名称，可以自定义，用于在客户端中标识该服务器。
'"command": "uv"': 指定启动服务器的命令为 'uv'，确保您的环境中已安装 'uv' 包管理器。
'"args"': 启动命令的参数列表。
- '"--directory"': 指定 PinThePiece 服务器代码所在的目录，请务必将其替换为您本地 PinThePiece 仓库的绝对路径。
- '"run"': 'uv run' 子命令用于运行 Python 包。
- '"pinthepiece"': 指定要运行的 Python 包名称，即 'pinthepiece'。

注意: 请根据您的实际环境修改 '/path/to/pinthepiece' 为 PinThePiece 仓库的绝对路径。

基本使用方法

配置完成后，在支持 MCP 协议的客户端（如 Claude Desktop）中，您应该能够看到名为 "pinthepiece" 的服务器。客户端可以通过以下方式与 PinThePiece 服务器交互：

资源访问: 在客户端中可以使用 'note://{note_name}' 格式的 URI 访问存储在 PinThePiece 服务器中的笔记内容。例如，'note://my-first-note' 可以访问名为 "my-first-note" 的笔记内容。
工具调用: 客户端可以调用 PinThePiece 服务器提供的工具，例如：
- 调用 'add-note' 工具添加新笔记。
- 调用 'get-note' 工具获取指定名称的笔记内容。
- 调用 'search-notes' 工具搜索笔记。
Prompt 使用: 客户端可以使用 'summarize-notes' Prompt 模板，让服务器生成笔记摘要。

具体的操作方式取决于您使用的 MCP 客户端的功能和界面。请参考您使用的 MCP 客户端的文档，了解如何配置和使用 MCP 服务器以及如何利用 PinThePiece 服务器提供的资源、工具和 Prompt。

调试: 如果遇到问题，可以使用 MCP Inspector 工具进行调试，具体方法请参考仓库 README 文档中的 "Debugging" 章节。

关键词