Mcpsample

🚀 シンプルなMCPサーバー

このプロジェクトは、TypeScriptで作成されたシンプルなMCP（Model Context Protocol）サーバのサンプルです。ClaudeDesktopから利用することで、ファイル操作やシステム情報の取得が可能です。

🚀 クイックスタート

このMCPサーバーを使用するには、以下のセットアップ手順に従ってください。

1. 依存関係のインストール

npm install

2. ビルド

npm run build

3. ClaudeDesktop設定

ClaudeDesktopの設定ファイル（通常 %APPDATA%\Claude\claude_desktop_config.json）を編集します：

{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {}
    }
  }
}

重要: args の配列には、プロジェクトの dist/index.js への絶対パスを指定してください。

4. ClaudeDesktopの再起動

設定を反映するため、ClaudeDesktopを再起動してください。

✨ 主な機能

• read_file: ファイルの読み込み（許可されたディレクトリのみ）
• write_file: ファイルへの書き込み（許可されたディレクトリのみ）
• list_directory: ディレクトリの一覧表示（許可されたディレクトリのみ）
• get_system_info: システム情報の取得
• create_sample_file: サンプルファイルの作成（テスト用）
• get_allowed_paths: アクセス可能なパス一覧を表示（新機能）

📦 インストール

セットアップ手順は「クイックスタート」を参照してください。

💻 使用例

ClaudeDesktopで以下のようなリクエストを試してみてください：

基本的な使用法

システム情報の取得

システム情報を教えて

アクセス可能なパスの確認

アクセス可能なパス一覧を表示して

サンプルファイルの作成

test.txtという名前でサンプルファイルを作成して

ファイルの読み込み

test.txtの内容を読み込んで

ディレクトリの一覧表示

現在のディレクトリの一覧を表示して

ファイルへの書き込み

hello.txtに「Hello, MCP World!」と書き込んで

📚 ドキュメント

🔒 セキュリティ機能

このMCPサーバーにはパスアクセス制限機能が組み込まれており、安全なディレクトリのみへのアクセスを許可します。

許可されるディレクトリ

• ユーザーのDocuments/00_AI_Areaフォルダ（現在の設定）
• その他カスタム設定可能

ブロックされるディレクトリ

• システムディレクトリ（/etc、/bin、/Windows、/Program Files など）
• 機密情報ディレクトリ（.ssh、.aws、.config など）

許可されるファイル拡張子

.txt, .md, .json, .js, .ts, .html, .css, .py, .java, .cpp, .c, .h, .xml, .yaml, .yml, .log, .csv, .tsv, .sql, .sh, .bat, .ps1

🔧 設定のカスタマイズ

PathValidatorクラスの設定を変更することで、アクセス許可ルールをカスタマイズできます：

// 許可するディレクトリを追加
this.allowedPaths = [
  path.resolve(os.homedir(), 'Documents/00_AI_Area'),
  // カスタムパスを追加
  path.resolve('/path/to/your/allowed/directory'),
];

// 許可するファイル拡張子を追加
this.allowedExtensions = [
  '.txt', '.md', '.json',
  // 新しい拡張子を追加
  '.custom',
];

ファイル構成

simple-mcp-server/
├── src/
│   └── index.ts          # メインのサーバー実装
├── dist/                 # ビルド後のJavaScriptファイル
├── package.json          # プロジェクト設定
├── tsconfig.json         # TypeScript設定
└── README.md            # このファイル

トラブルシューティング

MCPサーバーが認識されない場合

1. ClaudeDesktopの設定ファイルのパスが正しいか確認
2. dist/index.js への絶対パスが正しいか確認
3. npm run build でビルドが正常に完了しているか確認
4. ClaudeDesktopを完全に再起動

ファイル操作でエラーが発生する場合

• ファイルパスが存在するか確認
• 適切な読み書き権限があるか確認
• 相対パスではなく絶対パスを使用してみる

セキュリティ関連のエラー

"許可されていないパスです"

• アクセスしようとしているパスが許可されたディレクトリ内にありません
• get_allowed_pathsツールを使用してアクセス可能なパスを確認してください

"許可されていないファイル拡張子です"

• サポートされていないファイル拡張子にアクセスしようとしています
• 許可された拡張子の一覧を確認し、必要に応じて設定を変更してください

デバッグモード

サーバーの動作ログは標準エラー出力に出力されます：

npm run dev 2> debug.log

カスタマイズ

新しいツールを追加するには：

1. TOOLS 配列に新しいツール定義を追加
2. setupToolHandlers() メソッドにハンドラーを追加
3. 対応するメソッドを実装

例えば、現在時刻を取得するツールを追加したい場合は、get_current_time のようなツールを実装できます。

🛡️ セキュリティ考慮事項

• パスアクセス制限: システムファイルや機密情報への不正アクセスを防止
• ファイル拡張子フィルタ: 実行可能ファイルや危険なファイル形式をブロック
• パス正規化: 相対パスや「..」を使った親ディレクトリへの不正アクセスを防止
• エラーハンドリング: 適切なエラーメッセージでセキュリティ違反を通知

よくある質問

Q: 新しいディレクトリにアクセスしたい場合は？

A: クラスの配列にパスを追加してサーバーを再起動してください。 PathValidator``allowedPaths

Q: セキュリティ制限を無効にできますか？

A: セキュリティ上推奨されませんが、メソッドで常に{ isValid: true, normalizedPath }を返すように変更できます。 validatePath

Q: 大きなファイルの処理は可能ですか？

A: 現在の実装では、ファイル全体をメモリに読み込むため、非常に大きなファイルの処理には適していません。

注意事項

• このサンプルは学習・テスト目的で作成されています
• 本番環境で使用する場合は、適切なエラーハンドリングとセキュリティ対策を追加してください
• ファイル操作は実行するユーザーの権限で行われます
• セキュリティ制限により、許可されたディレクトリ以外にはアクセスできません

厳重注意: このサーバーはローカル環境での使用を想定しています。本番環境で使用する場合は、追加のセキュリティ対策を検討してください。

📄 ライセンス

MIT License