AI导哈

文档同步工具

一个全面的解决方案，用于将项目文件同步到Google的Gemini文件搜索API，支持在VS Code、Cursor、MCP服务器和Web界面上实现AI驱动的代码理解和聊天功能。

  • by shoutout-labs
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 shoutout-labs/document-sync

使用说明

文档同步

一个全面的解决方案，用于将您的项目文件同步到Google的Gemini File Search API，从而实现VS code、Cursor、MCP服务器和web界面上的人工智能代码理解和聊天功能。

概述

文档同步由三个主要组件组成：

  1. VS代码/光标扩展 -将文件从工作区同步到Gemini文件搜索
  2. MCP服务器 -使AI代理能够通过模型上下文协议查询您的项目文件
  3. web客户端 -通过React web界面与您的项目文件聊天

演示

Direct link: [resources/Document_Sync__Living_Brain.mp4](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代码/光标扩展

  1. 从VS Code市场安装扩展或从源代码构建：
cd extension
npm install
npm run compile
  1. 按 F5 打开一个加载了扩展的新窗口，或将其打包：
npm run package
  1. 安装生成的 .vsix VS代码/光标中的文件。

MCP服务器

MCP服务器可以作为npm包使用：

npm install -g @shoutoutlabs/document-sync-mcp

或者直接与npx一起使用：

npx @shoutoutlabs/document-sync-mcp

web客户端

cd web-client
npm install

创建一个 .env 文件：

VITE_GEMINI_API_KEY=your_api_key_here

启动开发服务器：

npm run dev

用法

VS代码/光标扩展

  1. 首次设置:

    • 打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P)
    • 跑 Gemini File Search: Sync Files
    • 提示时输入Gemini API密钥
    • 输入工作区的项目名称
    • 选择要监视的目录（或使用工作区根目录）

  2. 正在同步文件:

    • 使用“Gemini Sync”活动栏图标
    • 点击“同步文件”将文件上传到Gemini文件搜索
    • 保存更改时，文件会自动同步

  3. 命令:

    • Gemini File Search: Sync Files -手动触发同步
    • Gemini File Search: Login to Gemini -更新API密钥
    • Gemini File Search: Change Project Name -更新项目名称
    • Gemini File Search: Change Watch Location -更改要监视的目录

  4. 配置:

    • 设置存储在 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"
      }
    }
  }
}

添加到光标

  1. 打开光标设置
  2. 导航至 特性 > 主控程序
  3. 点击 添加新的MCP服务器
  4. 配置：
    • 名字: gemini-file-search
    • 类型: command
    • 命令: npx -y @shoutoutlabs/document-sync-mcp
    • 环境变量: GEMINI_API_KEY = your_api_key_here

可用工具

  • ask_project(query: string, projectName?: string) -询问有关项目文件的问题

web客户端

  1. 启动开发服务器（请参阅上面的安装）
  2. 在浏览器中打开应用程序（通常 http://localhost:5173)
  3. 从列表中选择一个项目
  4. 开始和你的项目文件聊天吧！

项目结构

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密钥

运作原理

  1. 文件同步：扩展程序监视指定的目录，并在文件更改时将文件上载到Gemini File Search API
  2. 文件搜索：文件由Gemini索引，可以使用自然语言查询
  3. AI查询：MCP服务器和web客户端使用Gemini的文件搜索来回答有关代码库的问题
  4. 项目组织机构：文件按项目名称组织，允许多个项目共存

故障排除

扩展问题

  • 文件未同步：检查您的API密钥是否已设置并且监视位置是否正确
  • API错误：验证Gemini API密钥是否有效，并启用了文件搜索
  • 未找到项目：确保 document-sync.json 存在于您的工作区根目录中

MCP服务器问题

  • 服务器未启动：检查一下 GEMINI_API_KEY 设置正确
  • 未找到项目：确保 document-sync.json 存在于您的项目根目录或集合中 PROJECT_PATH 环境变量

Web客户端问题

  • API密钥错误：确保 VITE_GEMINI_API_KEY 设置在您的 .env 文件
  • 未找到项目：确保您已使用该扩展同步了至少一个项目

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

支持

有关问题和疑问，请在GitHub存储库上打开问题。

相关 MCP