MCP AI基本代理示例
概述
该项目演示了如何使用Vercel的AI SDK构建命令行AI代理，该SDK连接到Fundable MCP服务器，使用自然语言查询全面的VC数据集（公司、投资者、人员、融资轮次）。
主要目的： 这是一个简单明了的例子，显示了您可以使用Fundable MCP完成什么，而无需复杂的提示、多工具使用或大量的代码修改。这种简单性展示了MCP的强大功能- 下游用户应考虑更先进的生产技术 （见下文生产注意事项）。
目录
关于Fundable MCP
Fundable MCP服务器公开 5工具 查询我们的BigQuery实例，该实例包含9万多家公司、6万名投资者和80万人。
| 工具 | 目的 | 参数 |
|---|---|---|
| getDatasetContext | 会话开始时呼叫。 返回完整的数据集文档：表模式（DBML）、业务规则（以百万计的货币值）和连接模式。 | 无 |
| listDatasetTables | 快速浏览数据集中的所有可用表。 | 无 |
| getQuery示例 | 按类别访问20多个示例查询。在不确定如何构建查询或尝试失败后非常有用。 | category：查询类别（例如，“资金分析”、“人员和关系”） |
| getTableDetails | 获取特定表的列名、类型和约束。 | tableName：检查表 |
| 查询VC数据 ⭐ | 执行只读BigQuery SQL。验证查询（阻止写入、检查表/列），通过BigQueryRESTneneneba API执行，返回带有统计数据的JSON结果。 | sql：SQL查询 |
maxResults：结果限制（可选，最大10000） |
快速开始
# 1. Install dependencies
npm install
# 2. Configure environment
cp .env.example .env
# Edit .env with your MCP API key and AI provider key
# 3. Get an MCP API key (required)
# Contact jacob@tryfundable.ai to request an API key
# 4. Test connection
npm run test:connection
# 5. Start the agent
npm run dev先决条件和设置
先决条件
- Node.js 18+ 必需的
- MCP API密钥 用于Fundable服务器访问
- 联系 jacob@tryfundable.ai 请求API密钥
- API密钥 至少一家人工智能提供商（OpenAI、Anthropic或谷歌）
安装
# 1. Install dependencies
npm install
# 2. Configure environment
cp .env.example .env
# Edit .env with your configuration (see below)环境配置
编辑您的 .env 文件：
# ===========================================
# MCP Server Authentication (API Key - Recommended)
# ===========================================
MCP_SERVER_URL=https://fundable_mcp.jacob-57a.workers.dev/api-mcp
MCP_API_KEY=fundable_mcp_your-api-key-here
# ===========================================
# AI Provider (choose one)
# ===========================================
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_MODEL=gpt-5-mini
# GOOGLE_GENERATIVE_AI_API_KEY=your-api-key-here
# GOOGLE_MODEL=gemini-3-flash
# ANTHROPIC_API_KEY=sk-your-api-key-here
# ANTHROPIC_MODEL=claude-sonnet-4-5-20250929身份验证选项
| 方法 | 端点 | 最适合 |
|---|---|---|
| API密钥 （推荐） | /api-mcp | AI代理、脚本、程序化访问 |
| OAuth | /mcp | 基于浏览器的工具（Claude Desktop、MCP Inspector） |
API密钥：设置 MCP_API_KEY 在你的 .env -无需浏览器交互。
OAuth （替代）：删除 MCP_API_KEY 从 .env 并使用 /mcp 终点。第一个连接将打开一个用于GitHub登录的浏览器。
运行代理
CLI选项
代理支持以下命令行选项：
--provider=-指定AI提供者：openai,anthropic，或google
- 默认值：基于可用API密钥的自动检测（优先级：Google→ 开放人工智能→ 人类学） - 所使用的特定模型在env变量中定义
-v, --verbose-启用详细日志记录以查看工具调用和推理
- 违约： false
-h, --help-显示带有使用示例的帮助消息
CLI命令示例
# Test MCP server connection
npm run test:connection
# Run interactive CLI (auto-detects provider)
npm run dev
# Run with specific provider
npm run dev -- --provider=openai
npm run dev -- --provider=anthropic
npm run dev -- --provider=google
# Run with verbose logging of tool calls and results
npm run dev -- -v
# Combine options
npm run dev -- --provider=openai -v
# Show all available options
npm run dev -- --help
# Build for production
npm run build可用文本命令
- 自然问题 -询问公司、投资者、融资轮次等。
clear-重置对话历史记录exit或quit-退出CLI
使用示例
npm run dev运行后，使用自然语言与VC数据集交互：
You: What tables are available?
Agent: [calls getDatasetContext] The database contains tables for organizations,
deals, institutional_investments, people, and more...
You: Who are the top investors in fintech companies?
Agent: [calls queryVCData] Based on the data, the top fintech investors are...
You: Clear
Agent: Conversation history cleared.
You: Exit
Agent: Goodbye!存储库结构
mcp-ai-agent-example/
├── src/
│ ├── index.ts # Main CLI entry point
│ ├── agent.ts # AIAgent class (Vercel AI SDK + MCP)
│ ├── helpers.ts # CLI argument parsing & model selection
│ ├── prompt-loader.ts # Prompt management system
│ └── test-connection.ts # MCP connection test utility
├── tests/
│ ├── test-runner.ts # Test orchestration engine
│ ├── test-suite/ # Test cases by difficulty
│ └── helpers/ # LLM-based evaluation system
├── prompts.yaml # ⭐ Agent system prompts
└── .env.example # Environment template关键文件：
prompts.yaml：代理行为、查询预算、推理方法src/agent.ts：Vercel AI SDK+MCP集成src/helpers.ts：CLI参数解析和AI提供程序配置tests/test-runner.ts：代理质量评估框架
测试与评估
运行测试
# Connection test
npm run test:connection
# Run all test suites
npm run test:eval
# Run specific suite
npm run test:eval -- --suite=easy
# Run specific test
npm run test:eval -- --suite=easy --id=5
# Run with specific AI provider
npm run test:eval -- --suite=medium --provider=openai
# Combine options
npm run test:eval -- --suite=hard --provider=google测试框架
三个难度级别：
- 简单：简单查找、基本查询
- 中等：多步骤发现、聚合
- 困难：复杂连接，实体消歧
法学硕士作为评委评估 (holistic-evaluator.ts):
- 逻辑方法 -查询策略有意义吗？
- 答案正确性 -答案准确吗？
- 效率 -在预期的查询预算范围内（+2容差）？
结果： 存储在 tests/results/ 作为带有时间戳的JSON，带有通过/失败成绩、推理和完整跟踪。
AI提供商性能
所有型号都实现了类似的整体精度，但在速度、成本和工具效率方面有所不同：
- 谷歌双子座Flash 3：推理速度最快，成本最低，工具使用效率最低，尤其是在棘手的问题上
- OpenAI（gpt-5-mini）：成本与Gemini相似，但工具使用速度慢2倍，效率更高
- 人物摄影（克劳德·十四行诗4.5）：最有效的工具使用，与OpenAI类似的延迟，更高的成本
*看 /tests/results 用于跨难度级别的样本测试输出*
⚠️ 生产注意事项
这个例子使用相对简单的提示来演示MCP的核心功能。 对于生产使用，您应该实施更高级的提示技术：
提示增强功能：
- 返回格式特殊性： 添加对精确输出模式（JSON模式、markdown表、结构化数据）的提示
- 处理缺失信息： 设置护栏，以便代理知道何时停止搜索数据集中不存在的信息（例如，我们数据集中的一些人有linkedin网址，但不包含教育/就业历史——代理应该知道何时停止查找）
- 发现问题： 实现消歧流程（例如，“a16z”可能意味着a16z加密货币、a16z速跑或a16z主基金）
其他注意事项：
- 针对失败查询和API超时的错误处理
- 速率限制和查询限制
- 对话持续/恢复
- 结构化日志记录和成本监控
许可证
麻省理工学院