Mcpsample

🚀 簡單MCP服務器

這是一個用TypeScript編寫的簡單MCP（模型上下文協議）服務器示例。可在ClaudeDesktop中使用，支持文件操作和系統信息獲取。

🚀 快速開始

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。

✨ 主要特性

🔒 安全功能

此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：顯示可訪問的路徑列表（新功能）

📦 安裝指南

依賴安裝

npm install

項目構建

npm run build

💻 使用示例

基礎用法

在ClaudeDesktop中嘗試以下請求：

獲取系統信息

請告訴我係統信息

查看可訪問路徑

顯示可訪問的路徑列表

創建示例文件

創建一個名為test.txt的示例文件

讀取文件

讀取test.txt的內容

列出目錄

顯示當前目錄的列表

寫入文件

在hello.txt中寫入「Hello, MCP World!」

📚 詳細文檔

🔧 自定義配置

通過修改 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：雖然在安全方面不建議這樣做，但可以修改 validatePath 方法，使其始終返回 { isValid: true, normalizedPath }。

Q：可以處理大文件嗎？

A：當前實現會將整個文件加載到內存中，因此不適合處理非常大的文件。

注意事項

• 本示例僅用於學習和測試目的。
• 在生產環境中使用時，請添加適當的錯誤處理和安全措施。
• 文件操作將使用執行用戶的權限。
• 由於安全限制，僅允許訪問指定的目錄。

嚴重警告：本服務器僅適用於本地環境。在生產環境中使用時，請考慮額外的安全措施。

📄 許可證

MIT許可證