JinDaGe - mcpSample MCP Details

article

README

🚀 简单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服务器未被识别

检查ClaudeDesktop配置文件的路径是否正确。
确认 dist/index.js 的绝对路径是否正确。
检查 npm run build 是否成功完成。
完全重启ClaudeDesktop。

文件操作出错

检查文件路径是否存在。
确认是否有适当的读写权限。
尝试使用绝对路径而非相对路径。

安全相关错误

“这是不允许的路径”：尝试访问的路径不在允许的目录内，请使用 get_allowed_paths 工具查看可访问的路径。
“这是不允许的文件扩展名”：尝试访问的文件扩展名不受支持，请查看允许的扩展名列表并根据需要更改设置。

调试模式

服务器的操作日志将输出到标准错误输出：

npm run dev 2> debug.log

自定义扩展

要添加新工具，请按以下步骤操作：

在 TOOLS 数组中添加新的工具定义。
在 setupToolHandlers() 方法中添加处理程序。
实现相应的方法。

例如，如果要添加一个获取当前时间的工具，可以实现 get_current_time 这样的工具。

🛡️ 安全注意事项

路径访问限制：防止对系统文件和机密信息的非法访问。
文件扩展名过滤：阻止可执行文件和危险文件格式。
路径规范化：防止使用相对路径或「..」对父目录进行非法访问。
错误处理：通过适当的错误消息通知安全违规。

常见问题解答

Q：如果想访问新的目录怎么办？

A：请在 PathValidator 类的 allowedPaths 数组中添加路径，然后重启服务器。

Q：可以禁用安全限制吗？

A：虽然在安全方面不建议这样做，但可以修改 validatePath 方法，使其始终返回 { isValid: true, normalizedPath }。

Q：可以处理大文件吗？

A：当前实现会将整个文件加载到内存中，因此不适合处理非常大的文件。

注意事项

本示例仅用于学习和测试目的。
在生产环境中使用时，请添加适当的错误处理和安全措施。
文件操作将使用执行用户的权限。
由于安全限制，仅允许访问指定的目录。

严重警告：本服务器仅适用于本地环境。在生产环境中使用时，请考虑额外的安全措施。

📄 许可证

MIT许可证