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 ファイルとして保存されます。

• Content：ノートの本文
• 作成日時／更新日時
• 整理用のタグ
• 説明（任意）
• 以下を含むメタデータ：
  • フォーマットのバージョン
  • 最終バックアップ日時
  • コンテンツのチェックサム

リソース

このサーバーは、以下の機能を備えたノート保存システムを実装しています。

• 個々のノートにアクセスするためのカスタム note:// URI スキーム
• 各ノートリソースの内容：
  • Name：一意の識別子
  • Content：本文
  • Description：任意の説明
  • Tags：分類用タグのリスト
  • Metadata：バージョンと整合性に関する情報
  • MIME タイプ：text/plain

データ安全機能

• アトミック操作：破損を防ぐため、すべてのファイル書き込みにアトミック操作を使用します
• バックアップシステム：変更前に自動バックアップを実行します
• バージョン管理：将来の互換性に備えてファイル形式をバージョン管理します
• データ検証：チェックサムの検証と整合性チェックを行います
• 同時アクセス：スレッドセーフを確保するためにファイルロックを使用します
• エラー復旧：ロールバック機能を備えた、トランザクションに似た操作を行います

プロンプト

このサーバーが提供するプロンプトは1つです。

• summarize-notes：保存されているすべてのノートの要約を作成します
  • 詳細度（brief／detailed）を指定する任意の「style」引数
  • 現在のすべてのノートとスタイル設定を組み合わせたプロンプトを生成します

ツール

このサーバーが実装するツールは1つです。

• 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

これにより、ソース配布物と wheel 配布物が dist/ ディレクトリに作成されます。

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 にブラウザーからアクセスして、デバッグを開始できます。

エラー処理

サーバーは包括的なエラー処理を実装しています。

• スタックトレースを含む詳細なエラーログ
• 一時ファイルの自動クリーンアップ
• 中断された操作からの復旧
• バックアップの復元機能
• 読み込み／保存時のデータ検証