内容
# 法式草莓 🍓
<p align="center">
<img src="assets/fraise.png" alt="法式草莓" width="240" />
<br />
<strong><em>和我说话</em></strong>
</p>
**适用于所有支持_MCP_的语音交互。**
法式草莓是一款语音优先的MCP主机。你说话，它会判断哪个MCP服务器可以处理你的意图并调用它。公共服务器（Slack、Jira、GitHub）或你自己构建的私有服务器。添加功能意味着在配置文件中添加服务器，而不是更改法式草莓。
详见 [ROADMAP.md](ROADMAP.md) 了解完整计划。
---
## 工作原理
```
你说话
└─ Deepgram语音转文本 → 文本
└─ 大型语言模型查看所有连接的MCP服务器上的工具
└─ 选择工具 → 法式草莓路由调用
├─ Slack MCP （公共）
├─ Jira MCP （公共）
├─ 日历MCP （私有 — 由我们构建）
├─ 记忆MCP （私有 — 本地SQLite）
└─ 计算器 （内置，今天）
└─ 结果 → 大型语言模型 → Deepgram文本转语音 → 你听到它
```
- **前端** — React + Vite。动画ElevenLabs WebGL球体，根据代理状态（空闲 → 监听 → 思考 → 说话）做出反应。麦克风音频通过AudioWorklet捕获，并作为线性16位PCM通过WebSocket流式传输。
- **后端** — FastAPI。一个单一的`/ws` WebSocket连接你的麦克风到 [Deepgram的语音代理](https://developers.deepgram.com/docs/voice-agent) （语音转文本 + 大型语言模型 + 文本转语音在一个套接字中）。当大型语言模型选择工具时，法式草莓在正确的MCP服务器上运行它并返回结果。工具会自动发现 — 无需硬编码。
- **MCP层** — 内置工具是FastMCP `@mcp.tool`函数。一个 `MCPManager` 连接到 `mcp_servers.json` 中列出的每个服务器（`builtin` / `stdio` / `http`），聚合它们的工具，并将每个调用路由到拥有它的服务器。
---
## 布局
```
frontend/
src/
App.tsx 语音UI
Orb.tsx ElevenLabs WebGL球体（延迟加载）
useVoiceAgent.ts 麦克风 + 播放 + WebSocket钩子
public/
pcm-worklet.js AudioWorklet：Float32 → 16 kHz Int16 PCM
backend/
app/
main.py FastAPI应用 — /ws, /health, /mcp, 提供前端
voice_agent.py Deepgram桥 + MCP函数调用处理程序
mcp_manager.py 连接到MCP服务器，聚合 + 路由工具
mcp_server.py 内置FastMCP工具（@mcp.tool）
mcp_servers.json MCP服务器配置（builtin / stdio / http）
requirements.txt
```
---
## 在本地运行
### 后端
```bash
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
```
在仓库根目录下创建 `.env` 文件：
```
DEEPGRAM_API_KEY=your_key_here
```
启动服务器：
```bash
uvicorn app.main:app --reload --port 8000
```
端点：
| 路径 | 描述 |
|------|-----------|
| `/health` | 存活检查 → `{"ok": true}` |
| `/ws` | 语音WebSocket |
| `/mcp/` | MCP服务器（可流式HTTP） |
### 前端
```bash
cd frontend
npm install
npm run dev
```
在 <http://localhost:5173> 打开。先启动后端 — 球体显示 **离线** 直到WebSocket连接。点击球体开始说话。
**生产构建** （后端提供UI）：
```bash
cd frontend && npm run build
# 然后访问 http://localhost:8000
```
---
## 技术
React 19 · TypeScript · Vite 6 · Three.js（球体）· Web Audio API
FastAPI · FastMCP · pydantic · Deepgram语音代理 · Python 3.11+
