🤖 AI PC助手MCP服务器
一个生产就绪的模型上下文协议（MCP）服务器，使AI助手能够在您的计算机上安全地执行实际操作。具有文件系统管理、本地搜索、命令执行、剪贴板访问等功能。
通过许可证验证为第一天货币化而构建。
特性
文件系统工具
- 列表文件 -列出包含元数据的目录内容（递归可选）
- read_file -读取文件内容
- write_file -写入或创建文件
- 删除文件 -删除文件或目录
- move_file -移动或重命名文件
搜索工具
- 搜索文件 -按名称查找文件（递归，最大结果限制）
- 搜索内容 -在文件中搜索文本内容
命令执行
- 运行命令 -执行shell命令（仅允许列出）
- list_allowed_命令 -查看允许的命令
系统运维
- launch_app -启动应用程序（平台感知：macOS/Windows/Linux）
- get_clipboard -读取剪贴板内容
- set_clipboard -写入剪贴板
自动化
- create_folder_structure -创建嵌套文件夹层次结构
- bulk_name -使用前缀/后缀重命名多个文件
- cleanup_desktop -按类型自动组织文件
本地存储
- kv_set -在本地存储笔记或数据
- kv_get -检索存储值
- kv_delete -删除存储的值
- kv_list -列出所有存储的密钥
- kv_clear -清除所有存储
需求
- Node.js 16+
- npm或纱线
- macOS、Windows或Linux
安装
1.克隆或下载
cd chhotu_sa_mcp_mvp
npm install2.获得许可证
首次用户：
npm run setup-license这将在以下位置创建演示许可证 ~/.mcp-license （有效期为90天）。对于生产用途，请联系支持人员获取商业许可证。
3.建造
npm run build跑步
发展模式
npm run dev生产模式
npm run build
npm start服务器将：
- 验证您的许可证
- 在stdio上启动MCP服务器（用于Claude Desktop等）
- 在以下位置启动HTTP传输
http://127.0.0.1:3000/mcp - 在以下位置启动WebSocket传输
ws://127.0.0.1:4000
配置
环境变量
NODE_ENV=production # Set to 'production' for stricter security
PORT=3000 # HTTP server port
WS_PORT=4000 # WebSocket server port
DEBUG=true # Enable debug logging许可证
许可证文件存储在 ~/.mcp-license （Unix/Mac）或 %USERPROFILE%\.mcp-license （Windows）
要重新生成许可证，请执行以下操作：
npm run setup-license集成示例
克劳德桌面版
添加到 claude_desktop_config.json:
{
"mcpServers": {
"chhotu": {
"command": "node",
"args": ["/path/to/dist/server.js"]
}
}
}ChatGPT与自定义GPT
通过HTTP或WebSocket连接：
- HTTP终结点：
http://127.0.0.1:3000/mcp - WebSocket端点：
ws://127.0.0.1:4000
程序化使用
import { runCommand } from './src/core/commands.js';
import { readFileContents } from './src/core/fileSystem.js';
// Run a command
const result = await runCommand('ls -la');
console.log(result.stdout);
// Read a file
const content = await readFileContents('/path/to/file.txt');
console.log(content);安全模型
允许列出的命令
默认情况下只允许使用以下shell命令：
- 文件操作：
ls,find,grep,cat,stat,file - 系统：
pwd,whoami,date,uname,which - 媒体：
ffmpeg,convert,imagemagick,sips
在开发模式中添加更多内容：
import { addAllowedCommand } from './src/core/commands.js';
addAllowedCommand('my-safe-tool');路径安全
- 阻止目录遍历(
../攻击） - 在允许的路径内验证文件访问权限
- 清除错误消息
误差边界
所有工具都返回结构化、安全的响应：
{
"success": false,
"error": "File not found",
"code": "FILE_NOT_FOUND"
}项目结构
chhotu_sa_mcp_mvp/
├── server.ts # Main MCP server entry point
├── package.json # Dependencies
├── tsconfig.json # TypeScript config
├── src/
│ ├── config/
│ │ ├── index.ts # Config initialization
│ │ └── license.ts # License validation (HMAC)
│ ├── core/
│ │ ├── fileSystem.ts # File operations
│ │ ├── search.ts # File/content search
│ │ ├── commands.ts # Command execution
│ │ ├── apps.ts # App launching
│ │ ├── clipboard.ts # Clipboard access (platform-aware)
│ │ └── kv.ts # Key-value store
│ ├── tools/
│ │ ├── index.ts # Tool registration
│ │ ├── fileTools.ts # File system tools
│ │ ├── searchTools.ts # Search tools
│ │ ├── commandTools.ts # Command execution
│ │ ├── systemTools.ts # App/clipboard tools
│ │ ├── automationTools.ts # Bulk operations
│ │ └── kvTools.ts # KV store tools
│ └── utils/
│ ├── platform.ts # Platform detection (macOS/Windows/Linux)
│ ├── paths.ts # Safe path handling
│ └── errors.ts # Error sanitization
└── README.md发展
添加新工具
- 在中创建核心模块
src/core/:
export async function myOperation(input: string): Promise {
// Implementation
}- 在中创建工具包装器
src/tools/:
import { z } from 'zod';
import { myOperation } from '../core/myModule.js';
export const MyToolInputSchema = z.object({
input: z.string(),
});
export async function myTool(input: z.infer) {
try {
const result = await myOperation(input.input);
return { content: [{ type: 'text', text: JSON.stringify(result) }] };
} catch (error) {
return { content: [createErrorResponse('ERROR', String(error))] };
}
}- 注册
src/tools/index.ts:
server.tool('my_tool', 'Description', MyToolInputSchema, myTool);测试
npm run dev
# In another terminal, test with curl
curl -X POST http://127.0.0.1:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_files","arguments":{"path":"~"}}}'变现
许可证验证
服务器使用HMAC-SHA256令牌验证：
import { generateLicenseToken, validateLicenseToken } from './src/config/license.js';
// Generate a new license (for resellers)
const token = generateLicenseToken('customer@example.com');
// Validate at runtime (automatic in server startup)
const result = validateLicenseToken(token);
if (result.isValid) {
console.log(`Valid for: ${result.licensee}`);
}默认情况下，许可证在90天后过期。修改 src/config/license.ts 不同的术语。
故障排除
许可证无效
# Regenerate license
npm run setup-license不允许命令
添加到允许列表中 src/core/commands.ts 或者使用开发模式。
平台特定问题
macOS： 确保 pbcopy/pbpaste 可用的 窗户： 剪贴板操作需要PowerShell Linux： 安装 xclip 或 xsel 用于剪贴板
性能和限制
- 文件搜索：默认情况下限制为100个结果
- 命令超时：30秒
- 剪贴板：最大10MB
- HTTP缓冲区：1MB
许可证
专有-根据.mcp许可模式许可
支持
有关问题或功能请求，请联系：support@example.com
______________________________________________________________________
版本： 1.0.0\ 最后更新时间： 2025年11月