文档同步
一个全面的解决方案，用于将您的项目文件同步到Google的Gemini File Search API，从而实现VS code、Cursor、MCP服务器和web界面上的人工智能代码理解和聊天功能。
概述
文档同步由三个主要组件组成：
- VS代码/光标扩展 -将文件从工作区同步到Gemini文件搜索
- MCP服务器 -使AI代理能够通过模型上下文协议查询您的项目文件
- web客户端 -通过React web界面与您的项目文件聊天
演示
Your browser does not support the video tag.
Direct link: resources/Document_Sync__Living_Brain.mp4
特性
- 🔄 自动文件同步 -将您的项目文件同步到Gemini File Search API
- 🤖 AI驱动的查询 -使用Gemini询问有关代码库的问题
- 📁 项目管理 -按项目名称组织文件
- 🎯 选择性同步 -选择要监视和同步的特定目录
- 🔌 MCP集成 -与Claude Desktop、Cursor和其他MCP兼容工具一起使用
- 🌐 web界面 -通过现代React UI与您的项目聊天
先决条件
- Node.js （v18或更高版本）
- VS Code 或 光标 （v1.85.0或更高版本）
- Google Gemini API密钥 -从以下地址获取您的 谷歌人工智能工作室
安装
VS代码/光标扩展
- 从VS Code市场安装扩展或从源代码构建：
cd extension
npm install
npm run compile- 按
F5打开一个加载了扩展的新窗口，或将其打包：
npm run package- 安装生成的
.vsixVS代码/光标中的文件。
MCP服务器
MCP服务器可以作为npm包使用：
npm install -g @shoutoutlabs/document-sync-mcp或者直接与npx一起使用：
npx @shoutoutlabs/document-sync-mcpweb客户端
cd web-client
npm install创建一个 .env 文件：
VITE_GEMINI_API_KEY=your_api_key_here启动开发服务器：
npm run dev用法
VS代码/光标扩展
- 首次设置:
- 打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P) - 跑 Gemini File Search: Sync Files - 提示时输入Gemini API密钥 - 输入工作区的项目名称 - 选择要监视的目录（或使用工作区根目录）
- 正在同步文件:
- 使用“Gemini Sync”活动栏图标 - 点击“同步文件”将文件上传到Gemini文件搜索 - 保存更改时，文件会自动同步
- 命令:
- Gemini File Search: Sync Files -手动触发同步 - Gemini File Search: Login to Gemini -更新API密钥 - Gemini File Search: Change Project Name -更新项目名称 - Gemini File Search: Change Watch Location -更改要监视的目录
- 配置:
- 设置存储在 document-sync.json 在您的工作区根目录中 - 包含 projectName 和 watchLocation 设置
MCP服务器
运行服务器
设置API密钥并运行：
export GEMINI_API_KEY="your_api_key_here"
npx @shoutoutlabs/document-sync-mcp添加到Claude桌面
增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：
{
"mcpServers": {
"gemini-file-search": {
"command": "npx",
"args": [
"-y",
"@shoutoutlabs/document-sync-mcp"
],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}添加到光标
- 打开光标设置
- 导航至 特性 > 主控程序
- 点击 添加新的MCP服务器
- 配置：
- 名字: gemini-file-search - 类型: command - 命令: npx -y @shoutoutlabs/document-sync-mcp - 环境变量: GEMINI_API_KEY = your_api_key_here
可用工具
ask_project(query: string, projectName?: string)-询问有关项目文件的问题
web客户端
- 启动开发服务器（请参阅上面的安装）
- 在浏览器中打开应用程序（通常
http://localhost:5173) - 从列表中选择一个项目
- 开始和你的项目文件聊天吧！
项目结构
document-sync/
├── extension/ # VS Code/Cursor extension
│ ├── extension.ts # Main extension code
│ ├── geminiService.ts # Gemini API integration
│ ├── package.json # Extension manifest
│ └── resources/ # Extension assets
├── mcp-server/ # MCP server for AI agents
│ ├── src/
│ │ ├── index.ts # MCP server entry point
│ │ └── gemini.ts # Gemini integration
│ └── package.json
└── web-client/ # React web application
├── src/
│ ├── App.tsx
│ ├── components/
│ └── services/
└── package.json发展
构建扩展
cd extension
npm install
npm run compile # Compile TypeScript
npm run watch # Watch mode for development
npm run package # Create .vsix package构建MCP服务器
cd mcp-server
npm install
npm run build构建Web客户端
cd web-client
npm install
npm run dev # Development server
npm run build # Production build
npm run preview # Preview production build配置
扩展设置
该扩展创建了一个 document-sync.json 工作区根目录中的文件：
{
"projectName": "my-project",
"watchLocation": "/path/to/watch"
}环境变量
MCP服务器：
GEMINI_API_KEY（必需）-您的Gemini API密钥PROJECT_PATH（可选）-项目根目录的绝对路径
Web客户端：
VITE_GEMINI_API_KEY（必需）-您的Gemini API密钥
运作原理
- 文件同步：扩展程序监视指定的目录，并在文件更改时将文件上载到Gemini File Search API
- 文件搜索：文件由Gemini索引，可以使用自然语言查询
- AI查询：MCP服务器和web客户端使用Gemini的文件搜索来回答有关代码库的问题
- 项目组织机构：文件按项目名称组织，允许多个项目共存
故障排除
扩展问题
- 文件未同步：检查您的API密钥是否已设置并且监视位置是否正确
- API错误：验证Gemini API密钥是否有效，并启用了文件搜索
- 未找到项目：确保
document-sync.json存在于您的工作区根目录中
MCP服务器问题
- 服务器未启动：检查一下
GEMINI_API_KEY设置正确 - 未找到项目：确保
document-sync.json存在于您的项目根目录或集合中PROJECT_PATH环境变量
Web客户端问题
- API密钥错误：确保
VITE_GEMINI_API_KEY设置在您的.env文件 - 未找到项目：确保您已使用该扩展同步了至少一个项目
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交拉取请求。
支持
有关问题和疑问，请在GitHub存储库上打开问题。