Voiceflow MCP 服务器 - 完整文档

什么是MCP？

MCP（模型上下文协议） 这是一个标准化协议，允许人工智能应用安全地连接到外部数据源和工具。可以将其视为一个通用适配器，使像Cursor这样的人工智能助手能够访问并与各种服务和文档进行交互。

关键MCP优势：

标准化接口一种适用于所有人工智能工具的协议
安全通信通过标准输入输出使用带有适当认证的JSON-RPC
工具发现人工智能可以动态发现并使用可用功能
实时互动AI与外部服务之间的实时通信

MCP实战应用：

Cursor AI ←→ MCP Protocol ←→ Voiceflow Documentation Server

______________________________________________________________________

我们为何建造这个

问题

Voiceflow 开发者经常需要：

浏览大量文档（333页以上）
获取具体的实施细节
查找代码示例和集成模式
了解API端点和配置

解决方案

我们的Voiceflow MCP服务器提供：

即时访问通过AI技术搜索所有Voiceflow文档
情境化答案基于文档内容的智能回复
块级精度查找精确章节，而非整页内容
Markdown 优先清晰、有条理的内容，助力AI更好地理解
实时更新始终紧跟最新文档

非常适合：

Cursor AI（游标人工智能）加强发展援助
Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”，但“克劳德桌面版”更准确地传达了这是Claude的一个桌面应用程序版本的意思）Voiceflow特定知识
任何MCP兼容的AI通用Voiceflow文档访问

______________________________________________________________________

它是如何工作的

1. 文献发现

# Fetches sitemap and discovers all documentation URLs
urls = await voiceflow.fetch_sitemap()  # Finds 333+ pages

2. 智能内容抓取

# Tries .md URLs first, falls back to HTML
doc = await voiceflow.fetch_markdown_content(url)

3. 智能分块

# Breaks documents into semantic chunks by headings
chunks = voiceflow.chunk_markdown(content)

4. 语义搜索

# Uses AI embeddings for intelligent search
results = await voiceflow.search_documents(query)

5. AI驱动的答案

# Combines multiple chunks for comprehensive answers
answer = await voiceflow.answer_question(question)

______________________________________________________________________

架构概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Cursor AI     │◄──►│  MCP Protocol    │◄──►│ Voiceflow MCP   │
│                 │    │  (JSON-RPC)      │    │    Server       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────┐
                                               │  Documentation  │
                                               │     Cache       │
                                               └─────────────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────┐
                                               │   Embeddings    │
                                               │   (Chunks)      │
                                               └─────────────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────┐
                                               │ Voiceflow Docs  │
                                               │  (333+ pages)   │
                                               └─────────────────┘

______________________________________________________________________

主要服务器功能

核心类

`DocumentCache`

目的文档内容和嵌入向量的内存存储

class DocumentCache:
    def __init__(self):
        self.cache: Dict[str, Dict[str, Any]] = {}      # URL → Document data
        self.embeddings: Optional[np.ndarray] = None    # Chunk embeddings
        self.documents: List[Dict[str, Any]] = []       # Chunk metadata

关键方法：

get(url)检索缓存的文档
set(url, content)存储文档数据
has_embeddings()检查是否已构建嵌入

`VoiceflowMCP`

目的主服务器类，负责处理所有Voiceflow文档操作

class VoiceflowMCP:
    def __init__(self):
        self.base_url = "https://docs.voiceflow.com"
        self.cache = DocumentCache()
        self.embedding_model = SentenceTransformer('all-MiniLM-L6-v2')
        self.http_client = httpx.AsyncClient()

核心功能

1. `fetch_sitemap()`

目的发现所有可用的文档页面

async def fetch_sitemap(self) -> List[str]:
    """Fetch and parse the sitemap to get all documentation URLs"""

它是如何工作的:

向（某处）发出HTTP请求 https://docs.voiceflow.com/sitemap.xml
使用ElementTree解析XML站点地图
提取全部 `` 包含URL的元素
返回包含333+个文档URL的列表

示例输出：

[
    "https://docs.voiceflow.com/docs/authentication",
    "https://docs.voiceflow.com/docs/custom-actions",
    "https://docs.voiceflow.com/reference/authentication",
    # ... 330+ more URLs
]

2. `fetch_markdown_content(url)`

目的获取文档内容，并具备智能回退机制

async def fetch_markdown_content(self, url: str) -> Optional[Dict[str, Any]]:
    """Fetch markdown content from a Voiceflow documentation URL"""

它是如何工作的：

检查缓存如果可用，返回缓存内容
尝试使用.md格式的URL尝试 {url}.md 首先
内容验证检查响应是否为Markdown格式
备用方案；回退方案如需必要，将回退到原始URL
速率限制对429/5xx错误实施指数退避策略
处理提取标题、描述，创建块（或片段）
缓存存储处理后的内容以备将来使用

示例：

# Input: "https://docs.voiceflow.com/docs/custom-actions"
# Tries: "https://docs.voiceflow.com/docs/custom-actions.md"
# Output: {
#     "url": "https://docs.voiceflow.com/docs/custom-actions",
#     "markdown_url": "https://docs.voiceflow.com/docs/custom-actions.md",
#     "title": "Custom action step",
#     "description": "The Custom Action step allows you to...",
#     "content": "cleaned markdown content",
#     "raw_content": "original markdown",
#     "chunks": [{"heading": "Overview", "markdown": "..."}, ...]
# }

3. `chunk_markdown(md)`

目的智能地将文档拆分为可搜索的部分

def chunk_markdown(self, md: str) -> List[Dict[str, Any]]:
    """Chunk markdown by headings for better search granularity"""

它是如何工作的：

逐行处理遍历Markdown行
代码块检测保持代码块完整无损
标题检测使用正则表达式来查找 #， ##， ### 标题
块创建在每个标题处创建新段落
内容保存保持原始格式

示例：

# Input markdown:
"""
# Custom Action step
Overview text here...

## Configuration
Config details...

// Code block preserved const action = {};


"""

# 输出块：

\[
{"标题": "自定义操作步骤", "markdown": "# 自定义操作步骤\\n这里是概述文本..."}，
{"标题": "配置", "markdown": "## 配置\\n配置详情..."}，
{"标题": "", "markdown": "`javascript\nconst action = {};\n`"}
\]

4. `build_embeddings()`

Purpose: Creates AI embeddings for semantic search

async def build_embeddings(self) -> None:
    """Build embeddings for all cached documents using chunks"""

它是如何工作的：

分块处理遍历所有文档块
文本清洗去除Markdown语法、链接和代码块
嵌入生成使用SentenceTransformer创建向量
元数据存储存储带有嵌入信息的块元数据
向量存储将嵌入存储为NumPy数组

文本处理流水线：

# Original chunk: "## Configuration\n* **name**: API key value"
# Cleaned text: "Configuration name API key value"
# Embedding: [0.1, -0.3, 0.7, ...] (384-dimensional vector)

5. `search_documents(query, limit)`

目的通过文档执行语义搜索

async def search_documents(self, query: str, limit: int = 5) -> List[Dict[str, Any]]:
    """Search through cached documents using semantic similarity"""

它是如何工作的：

查询嵌入将搜索查询转换为向量
相似度计算计算与所有块的余弦相似度
排名按相似度得分对结果进行排序
过滤返回前N个最相关的结果
元数据丰富化为结果添加相似度评分

示例:

# Query: "How to authenticate with API"
# Results:
[
    {
        "title": "Authentication",
        "heading": "API Key Setup",
        "snippet": "To authenticate with the Voiceflow API...",
        "url": "https://docs.voiceflow.com/docs/authentication",
        "markdown_url": "https://docs.voiceflow.com/docs/authentication.md",
        "similarity": 0.85
    },
    # ... more results
]

6. `answer_question(question)`

目的为问题提供基于人工智能的答案

async def answer_question(self, question: str) -> Dict[str, Any]:
    """Answer a question about Voiceflow using documentation"""

它是如何工作的:

文档搜索使用语义搜索查找相关片段
答案构建将多个代码片段组合在一起
来源归属记录了使用了哪些文档
置信度评分计算总体置信水平
结构化响应返回带有来源的格式化答案

7. `warmup(limit)`

目的预加载文档以加快响应速度

async def warmup(self, limit: int = 120) -> None:
    """Warmup by fetching key documentation pages and building embeddings"""

它是如何工作的：

URL优先级排序获取 /reference 并且 /docs URLs 首先
批处理按顺序下载多页内容
内容处理提取并分块所有内容
嵌入式建筑创建可搜索的嵌入表示
缓存填充为服务器做好快速查询的准备

MCP协议功能

`handle_list_tools()`

目的列出适用于AI客户端的可用MCP工具

@app.list_tools()
async def handle_list_tools() -> List[Tool]:
    """List available tools"""

返回4个工具：

search_voiceflow_docs搜索文档
get_voiceflow_doc_page获取特定页面
ask_voiceflow_question提出问题
list_voiceflow_topics浏览主题

`handle_call_tool(name, arguments)`

目的执行来自AI客户端的MCP工具调用

@app.call_tool()
async def handle_call_tool(name: str, arguments: Dict[str, Any]) -> List[dict]:
    """Handle tool calls"""

工具处理程序:

搜索处理搜索查询，包括预热和缓存
获取页面获取特定的文档页面
提问提供基于人工智能的答案
列出主题显示可用主题的组和列表

______________________________________________________________________

测试文件说明

1. `test_server.py`

目的基本功能测试

# Tests core VoiceflowMCP functionality
async def test_server():
    # Test sitemap fetching
    urls = await voiceflow.fetch_sitemap()
    
    # Test document fetching
    doc = await voiceflow.fetch_markdown_content(test_url)
    
    # Test search functionality
    results = await voiceflow.search_documents(query)
    
    # Test Q&A functionality
    result = await voiceflow.answer_question(question)

它测试的内容：

✅ 网站地图解析（333个URL）
✅ 使用.md URL获取文档
✅ 使用嵌入进行语义搜索
✅ 带置信度评分的问答系统
✅ 基于块的搜索结果

2. `test_cursor_simulation.py`

目的模拟Cursor的MCP通信

class MCPClientSimulator:
    async def simulate_initialize_request(self):
        # Tests MCP initialization handshake
        
    async def simulate_list_tools_request(self):
        # Tests tool discovery
        
    async def simulate_search_request(self):
        # Tests search tool execution
        
    async def simulate_question_request(self):
        # Tests Q&A tool execution

它测试的内容：

✅ MCP协议初始化
✅ 工具发现与列表
✅ JSON-RPC 请求/响应格式
✅ 使用真实参数执行工具
✅ 错误处理和超时设置

3. `test_mcp_client.py`

目的用于测试的简单MCP客户端

async def test_mcp_server():
    # Start MCP server process
    process = subprocess.Popen([sys.executable, "voiceflow_mcp_server.py"])
    
    # Send initialization request
    init_request = {...}
    process.stdin.write(json.dumps(init_request))
    
    # Read response
    response = process.stdout.readline()

它测试的内容:

✅ 服务器启动和初始化
✅ 基本的MCP协议通信
✅ 过程管理
✅ 响应验证

4. `interactive_test.py`

目的交互式测试界面

class InteractiveMCPTester:
    async def interactive_menu(self):
        # Provides menu-driven testing
        print("1. Search Documentation")
        print("2. Get Documentation Page")
        print("3. Ask Question")
        # ... more options

它提供了什么：

✅ 交互式菜单系统
✅ 手动工具测试
✅ 实时响应查看
✅ 用户友好的界面

5. `simple_test.py`

目的核心功能演示

async def test_voiceflow_functionality():
    # Tests all core functions
    
async def simulate_cursor_usage():
    # Simulates real Cursor scenarios

它所表明的是:

✅ 完整的服务器功能
✅ 真实使用场景
✅ 性能指标
✅ 成功/失败报告

6. `payload_test.py`

目的显示精确的MCP通信

class PayloadSimulator:
    def create_mcp_request(self, method: str, params: dict):
        # Creates JSON-RPC requests
        
    def create_mcp_response(self, result: dict):
        # Creates JSON-RPC responses

它所展示的：

✅ 正确的JSON-RPC请求格式
✅ 正确的 JSON-RPC 响应格式
✅ 实际有效载荷示例
✅ 通信协议详情

7. `test_improvements.py`

目的测试所有服务器改进

async def test_improvements():
    # Tests markdown-first fetching
    # Tests warmup functionality
    # Tests chunk-based search
    # Tests enhanced responses

async def test_specific_voiceflow_features():
    # Tests common Voiceflow topics

它验证的内容:

✅ 以Markdown为先的获取方式，备选方案备用
✅ 智能预热系统
✅ 基于块的嵌入表示
✅ 增强了响应格式
✅ 可投入生产的功能

______________________________________________________________________

使用示例

1. 基本搜索

# Search for custom actions
results = await voiceflow.search_documents("custom actions", limit=3)
for result in results:
    print(f"{result['title']} - {result['heading']}")
    print(f"Snippet: {result['snippet'][:100]}...")

2. 提出问题

# Ask about authentication
answer = await voiceflow.answer_question("How do I get an API key?")
print(f"Answer: {answer['answer']}")
print(f"Confidence: {answer['confidence']:.2f}")

3. 获取具体文件/文档

# Get custom actions page
doc = await voiceflow.get_documentation_page(
    "https://docs.voiceflow.com/docs/custom-actions"
)
print(f"Title: {doc['title']}")
print(f"Content: {doc['raw_content'][:500]}...")

4. 为提升表现进行热身

# Pre-load documentation
await voiceflow.warmup(limit=50)
print(f"Loaded {len(voiceflow.cache.cache)} documents")

______________________________________________________________________

配置

光标集成

在你的Cursor设置中添加：

{
  "mcpServers": {
    "voiceflow-docs": {
      "command": "python",
      "args": ["/path/to/voiceflow_mcp_server.py"],
      "env": {}
    }
  }
}

环境变量

# Optional: Custom configuration
export VF_MCP_CACHE_SIZE=1000
export VF_MCP_WARMUP_LIMIT=120
export VF_MCP_TIMEOUT=30

______________________________________________________________________

故障排除

常见问题

1. 服务器无法启动

# Check Python version
python --version  # Should be 3.8+

# Install dependencies
pip install -r requirements.txt

# Check MCP installation
python -c "import mcp; print(mcp.__version__)"

2. 未找到搜索结果

# Ensure warmup is complete
await voiceflow.warmup(limit=50)

# Check cache status
print(f"Cache size: {len(voiceflow.cache.cache)}")
print(f"Embeddings: {voiceflow.cache.has_embeddings()}")

3. 性能下降

# Increase warmup limit
await voiceflow.warmup(limit=200)

# Check embedding model
print(f"Model loaded: {voiceflow.embedding_model is not None}")

4. 文件缺失

# Check sitemap access
urls = await voiceflow.fetch_sitemap()
print(f"Found {len(urls)} URLs")

# Test specific URL
doc = await voiceflow.fetch_markdown_content("https://docs.voiceflow.com/docs/custom-actions")

调试模式

import logging
logging.basicConfig(level=logging.DEBUG)

# Run server with debug logging
python voiceflow_mcp_server.py

______________________________________________________________________

性能指标

典型性能

网站地图抓取约2秒
热身（50份文档）约30秒
搜索查询0.5秒左右
问题回答约1秒
页面获取约2秒

内存使用情况

基础服务器约100MB
拥有50份文档约200MB
拥有200份文档约400MB
带有嵌入表示+100MB

缓存效率

命中率预热后约95%
罚分小姐（或“失误小姐”，具体根据上下文确定）每次失误大约2秒
嵌入式构建100份文档大约需要10秒

______________________________________________________________________

本文档提供了对Voiceflow MCP服务器的全面了解，从高级概念到详细的实现细节一应俱全。该服务器旨在为AI驱动的开发工具提供无缝、智能的Voiceflow文档访问服务。

Voiceflow MCP

快速接入

详细介绍

Voiceflow MCP 服务器 - 完整文档

目录

什么是MCP？

关键MCP优势：

MCP实战应用：

我们为何建造这个

问题

解决方案

非常适合：

它是如何工作的

1. 文献发现

2. 智能内容抓取

3. 智能分块

4. 语义搜索

5. AI驱动的答案

架构概述

主要服务器功能

核心类

DocumentCache

VoiceflowMCP

核心功能

1. fetch_sitemap()

2. fetch_markdown_content(url)

3. chunk_markdown(md)

4. build_embeddings()

5. search_documents(query, limit)

6. answer_question(question)

7. warmup(limit)

MCP协议功能

handle_list_tools()

handle_call_tool(name, arguments)

测试文件说明

1. test_server.py

2. test_cursor_simulation.py

3. test_mcp_client.py

4. interactive_test.py

5. simple_test.py

6. payload_test.py

7. test_improvements.py

使用示例

1. 基本搜索

2. 提出问题

3. 获取具体文件/文档

4. 为提升表现进行热身

配置

光标集成

环境变量

故障排除

常见问题

1. 服务器无法启动

2. 未找到搜索结果

3. 性能下降

4. 文件缺失

调试模式

性能指标

典型性能

内存使用情况

缓存效率

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`DocumentCache`

`VoiceflowMCP`

1. `fetch_sitemap()`

2. `fetch_markdown_content(url)`

3. `chunk_markdown(md)`

4. `build_embeddings()`

5. `search_documents(query, limit)`

6. `answer_question(question)`

7. `warmup(limit)`

`handle_list_tools()`

`handle_call_tool(name, arguments)`

1. `test_server.py`

2. `test_cursor_simulation.py`

3. `test_mcp_client.py`

4. `interactive_test.py`

5. `simple_test.py`

6. `payload_test.py`

7. `test_improvements.py`