Vin Agent

VIN：虚拟行程导航器

一个可用于生产的模型上下文协议（MCP）服务器，通过无缝的Google API集成，将自然语言转换为可操作的日历事件、电子邮件通知和餐厅推荐。

🎯 问题陈述

管理复杂的行程和活动协调既费时又容易出错：

• 手动日历管理：创建事件、检查冲突并协调多个参与者的日程安排
• 零散的沟通：分别发送电子邮件以获取活动详情、场地建议和预订确认
• 场地探索：寻找和评估附近的餐厅或会议和活动场所
• 上下文切换：在日历应用程序、电子邮件客户端和餐厅搜索平台之间切换

🚀 解决方案

VIN（虚拟行程导航器）通过提供统一的、人工智能驱动的界面来解决这些挑战，该界面：

• 自动安排事件：将自然语言请求转换为具有冲突检测功能的结构化日历事件
• 简化沟通：生成并向所有参与者发送正式的电子邮件通知
• 增强场地探索：查找附近具有详细信息和预订功能的餐厅
• 无缝集成：通过模型上下文协议与Claude和其他LLM合作

✨ 特性

📅 智能日历集成

• 使用自动时间解析创建自然语言事件
• 实时冲突检测和解决
• 通过自动电子邮件通知进行与会者管理
• 具有时区感知的日程安排，具有灵活的持续时间选项

📧 自动电子邮件系统

• 事件通知的正式电子邮件生成
• CC/BCC功能，实现全面通信
• 草稿创建和直接发送功能

��️ 智能场馆发现

• 基于位置的餐厅搜索，可定制半径
• 详细的场地信息（评级、时间、联系方式）
• 价格水平和菜肴类型过滤
• 与Google Places API集成以获取实时数据

👥 联系人管理

• 内置联系人目录，可查找电子邮件
• 与电子邮件和日历工具无缝集成
• 基于JSON的联系人存储，便于管理

🤖 LLM集成

• 完全符合MCP（模型上下文协议）
• 与Claude、GPT-4和其他MCP兼容的LLM配合使用
• 复杂请求的自然语言处理
• 具有结构化数据的上下文感知响应

🛠️ 技术栈

• 后端：Python 3.8+
• MCP框架：FastMCP 2.0
• 谷歌API：Gmail、日历、地点
• 认证：OAuth 2.0，带有自动令牌刷新功能
• 数据存储：基于JSON的联系人管理
• 环境：具有依赖关系管理的虚拟环境
• 程序包管理器: 紫外线 （推荐）或pip

📋 先决条件

• Python 3.8或更高版本
• 谷歌云平台帐户
• 已启用Google API（Gmail、日历、地点）
• 已配置OAuth 2.0凭据
• 紫外线 （建议用于更快的依赖关系管理）

快速开始

1.克隆存储库

git clone https://github.com/yourusername/vin-agent.git
cd vin-agent

2.使用uv设置虚拟环境（推荐）

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

3.替代方案：使用pip设置

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

4.配置谷歌API

1. 创建谷歌云项目
2. 启用Gmail API、日历API和地点API
3. 创建OAuth 2.0凭据
4. 下载 credentials.json 并将其保存在.config/vin代理中/

5.设置环境变量

cp .env.example .env
# Edit .env with your configuration

6.通过谷歌进行身份验证

# With uv
uv run oauth_setup.py

# Or with python
python oauth_setup.py

7.启动MCP服务器

# With uv (recommended)
uv run mcp-server.py

# Or with python
python mcp-server.py

🤖 Claude桌面集成

例如，要在Claude Desktop中使用VIN，请将以下配置添加到您的Claude Desktop设置中：

{
  "mcpServers": {
    "vin": {
      "command": "/Users/baazilakhlaque/.local/bin/uv", # replace with global path to your uv installation
      "args": [
        "--directory",
        "/Users/baazilakhlaque/Desktop/vin", # replace with global path to repo
        "run",
        "mcp-server.py"
      ]
    }
  }
}

备注：更新路径以匹配您的实际安装目录和用户名。

⚙️ 配置

环境变量

# Your Gmail address (used as sender)
USER_EMAIL=your.email@gmail.com

# Google Maps API Key (for venue search)
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

# Default timezone for events
DEFAULT_TIMEZONE=America/New_York

# Default city for venue searches
CITY_DEFAULT=New York, NY

联系人管理

创建 contacts.json 文件以以下格式管理您的联系人目录：

{
    "John Doe": "john.doe@company.com",
    "Jane Smith": "jane.smith@company.com"
}

📖 使用示例

日历事件创建

“明天下午3点与约翰和简安排一次1小时的团队会议”

电子邮件通知

“向John和Jane发送一封关于项目更新的电子邮件”

餐厅探索

“推荐得克萨斯州达拉斯市中心的餐馆。”

�� 安全与隐私

• OAuth 2.0身份验证：安全身份验证
• 许可证管理：自动刷新令牌处理

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• FastMCP 对于MCP框架
• 谷歌API 用于Gmail、日历和地点集成
• Anthropic 适用于Claude和MCP协议
• 紫外线 用于快速Python包管理

______________________________________________________________________