README.md•7.24 kB
# Simple MCP Server
TypeScriptで作成されたシンプルなMCP（Model Context Protocol）サーバのサンプルです。ClaudeDesktopから使用して、ファイル操作やシステム情報の取得が可能です。
## 🔒 セキュリティ機能
この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`
## 機能
- **read_file**: ファイルの読み込み（許可されたディレクトリのみ）
- **write_file**: ファイルへの書き込み（許可されたディレクトリのみ）
- **list_directory**: ディレクトリの一覧表示（許可されたディレクトリのみ）
- **get_system_info**: システム情報の取得
- **create_sample_file**: サンプルファイルの作成（テスト用）
- **get_allowed_paths**: アクセス可能なパス一覧を表示（**新機能**）
## セットアップ
### 1. 依存関係のインストール
```bash
npm install
```
### 2. ビルド
```bash
npm run build
```
### 3. ClaudeDesktop設定
ClaudeDesktopの設定ファイル（通常 `%APPDATA%\Claude\claude_desktop_config.json`）を編集します：
```json
{
"mcpServers": {
"simple-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/your/project/dist/index.js"],
"env": {}
}
}
}
```
**重要**: `args` の配列には、プロジェクトの `dist/index.js` への絶対パスを指定してください。
### 4. ClaudeDesktopの再起動
設定を反映するため、ClaudeDesktopを再起動してください。
## 開発モード
開発中は以下のコマンドでサーバーを直接実行できます：
```bash
npm run dev
```
## 使用例
ClaudeDesktopで以下のようなリクエストを試してみてください：
### システム情報の取得
```
システム情報を教えて
```
### アクセス可能なパスの確認
```
アクセス可能なパス一覧を表示して
```
### サンプルファイルの作成
```
test.txtという名前でサンプルファイルを作成して
```
### ファイルの読み込み
```
test.txtの内容を読み込んで
```
### ディレクトリの一覧表示
```
現在のディレクトリの一覧を表示して
```
### ファイルへの書き込み
```
hello.txtに「Hello, MCP World!」と書き込んで
```
## 🔧 設定のカスタマイズ
`PathValidator`クラスの設定を変更することで、アクセス許可ルールをカスタマイズできます：
```typescript
// 許可するディレクトリを追加
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ツールを使用してアクセス可能なパスを確認してください
#### "許可されていないファイル拡張子です"
- サポートされていないファイル拡張子にアクセスしようとしています
- 許可された拡張子の一覧を確認し、必要に応じて設定を変更してください
### デバッグモード
サーバーの動作ログは標準エラー出力に出力されます：
```shell
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