Toco Toco

FastMCP服务器

一个全面的模型上下文协议（MCP）服务器实现，具有松果矢量数据库集成、OpenAI嵌入和RAG（检索增强生成）功能。

什么是MCP（模型上下文协议）？

模型上下文协议（MCP）是一个开放标准，使人工智能助手能够通过标准化的接口连接到外部数据源和工具。它允许像Claude这样的AI模型：

• 访问外部数据：连接到数据库、API和文件系统
• 执行工具：运行自定义函数和脚本
• 维护上下文：跟踪会话之间的对话和数据
• 扩展功能：在不重新训练模型的情况下添加新功能

MCP通过客户端-服务器架构工作，其中：

• MCP客户端：人工智能助手（Claude、Cursor等）
• MCP服务器：提供工具和数据访问的自定义服务器
• 传输层：通信协议（stdio、HTTP、WebSocket）

项目概述

此FastMCP服务器提供：

• 松果矢量数据库集成：创建、管理和查询向量索引
• OpenAI嵌入：将文本转换为高维向量
• RAG运营：使用语义搜索存储和检索文档
• 多种传输协议：支持stdio、HTTP和流式传输HTTP
• 异步操作：无阻塞操作，性能更佳

项目结构

mcp-server/
├── main.py                 # Server entry point
├── config.py              # Configuration management
├── pyproject.toml         # Project dependencies
├── src/
│   ├── server.py          # Main server setup
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── math_tools.py  # Basic math operations
│   │   ├── pinecone_tools/
│   │   │   └── pinecone_config.py  # Pinecone index management
│   │   └── rag_tools/
│   │       ├── rag_retrical.py     # Document retrieval
│   │       └── rag_store.py        # Document storage
│   ├── prompts/           # System prompts
│   └── resources/         # Static resources
└── test/                  # Test files

特性

🗄️ 松果矢量数据库工具

• create_index：创建新的向量索引
• delete_index：删除索引
• list_index：查看所有可用索引
• list_namespaces：列出索引中的命名空间

📚 RAG（检索增强生成）工具

• 松果商店：存储带有嵌入的文档
• 松果回收：语义搜索和文档检索

🔢 数学工具

• 添加：添加两个数字
• 乘：将两个数字相乘

安装和设置

先决条件

• Python 3.8+
• OpenAI API密钥
• 松果API键

1.克隆和设置

git clone 
cd mcp-server

2.安装依赖项

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

3.环境配置

创建一个 .env 文件或设置环境变量：

OPENAI_API_KEY=your-openai-api-key
PINECONE_API_KEY=your-pinecone-api-key
EMBEDDING_DIMENSIONS=3072
EMBEDDING_MODEL=text-embedding-3-large

4.运行服务器

开发模式（带检查员）

uv run mcp dev main.py

生产模式

uv run mcp run main.py

直接执行Python

uv run python main.py

与AI助手集成

Claude桌面集成

1. 找到Claude桌面配置

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

1. 添加MCP服务器配置

{
  "mcpServers": {
    "fastmcp-server": {
      "command": "/path/to/your/project/.venv/bin/python3",
      "args": ["/path/to/your/project/main.py"],
      "env": {
        "PINECONE_API_KEY": "your-pinecone-api-key",
        "OPENAI_API_KEY": "your-openai-api-key",
        "EMBEDDING_DIMENSIONS": "3072",
        "EMBEDDING_MODEL": "text-embedding-3-large"
      }
    }
  }
}

1. 重新启动克劳德桌面

光标集成

1. 打开光标设置
2. 导航到MCP配置
3. 添加服务器配置

{
  "name": "fastmcp-server",
  "command": "/path/to/your/project/.venv/bin/python3",
  "args": ["/path/to/your/project/main.py"],
  "env": {
    "PINECONE_API_KEY": "your-pinecone-api-key",
    "OPENAI_API_KEY": "your-openai-api-key"
  }
}

传输协议

1.stdio（默认）

• 用例：与AI助手直接集成
• 配置: mcp.run() （默认）
• 优点：简单、可靠、无需网络设置
• 缺点：单客户端连接

2.HTTP

• 用例：Web应用程序，多个客户端
• 配置: mcp.run(transport="http")
• 优点：多个客户端，网络集成
• 缺点：需要网络配置

3.可流式传输HTTP

• 用例：实时流媒体应用程序
• 配置: mcp.run(transport="streamable-http")
• 优点：实时更新、流式响应
• 缺点：更复杂的设置

4.WebSocket

• 用例：双向沟通
• 配置: mcp.run(transport="websocket")
• 优点：全双工通信
• 缺点：连接管理复杂性

使用示例

创建和管理索引

# Create a new index
await create_index("my-documents")

# List all indexes
await list_indexes()

# Delete an index
await delete_index("old-index")

存储文档

documents = [
    {
        "id": "doc_001",
        "content": "This is a sample document about machine learning.",
        "metadata": {
            "source": "ml_guide.pdf",
            "title": "Machine Learning Basics",
            "author": "John Doe"
        }
    }
]

await pinecone_store(
    index_name="my-documents",
    namespace="",
    documents=documents
)

正在检索文档

results = await pinecone_retrieve(
    index_name="my-documents",
    namespace="",
    query="machine learning algorithms",
    top_k=5
)

配置选项

嵌入模型

• text-embedding-3-small：1536尺寸，更快，更便宜
• 文本嵌入-3大：3072个维度，更准确，成本更高

松果指数设置

• 维度：必须与嵌入模型输出匹配
• 指标：余弦、欧几里得、点积
• 云：AWS、GCP、Azure

故障排除

常见问题

1. ModuleNotFoundError:没有名为“mcp”的模块

- 解决方案：使用安装依赖项 uv sync - 确保您正在使用虚拟环境

1. 尺寸不匹配

- 解决方案：确保索引维度与嵌入模型匹配 - 使用 text-embedding-3-large 3072个维度

1. 连接问题

- 检查API密钥是否正确 - 验证网络连接 - 重新启动MCP服务器

1. 传输错误

- 对于stdio：确保没有其他进程正在使用该传输 - 对于HTTP：检查端口可用性 - 对于WebSocket：验证WebSocket服务器是否正在运行

调试模式

# Enable debug logging
DEBUG=1 uv run python main.py

发展

添加新工具

1. 在中创建新的工具文件 src/tools/
2. 定义工具功能 @mcp.tool() 装饰器
3. 导入并注册 src/server.py

测试

# Run tests
uv run pytest

# Run specific test
uv run pytest test/test_rag_tools.py

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

\[在此处添加您的许可证信息\]

支持

对于问题和疑问：

• 在GitHub上创建问题
• 检查故障排除部分
• 在以下网址查看MCP文件https://modelcontextprotocol.io

______________________________________________________________________

备注：此服务器专为开发和生产使用而设计，具有适当的错误处理、异步操作和全面的日志记录功能。