松果经济图书MCP服务器
一种模型上下文协议（MCP）服务器，提供对包含经济书籍和学术论文的松果矢量数据库的只读访问。
主要特征： Pinecone的推理API提供的自然语言语义搜索-只需简单的英语询问，即可自动获得相关结果。
服务器还提供专门的元数据搜索工具，用于按作者、主题、书籍、页面范围等进行精确过滤。
特性
10个综合搜索工具
所有搜索工具都使用Pinecone推理API提供的语义搜索
主要搜索工具
- 语义研究 -自然语言搜索（默认/简单）
- 使用松果推理自动嵌入您的查询 - 最适合：“市场均衡理论”、“自动化的影响”
- 语义搜索与过滤器 -语义搜索+元数据过滤器
- 将自然语言与精确过滤相结合 - 最适合：瓦西里·莱昂蒂夫（Wassily Leontief）著作中的“劳动生产率”
过滤语义搜索
以下所有工具都将语义搜索与元数据过滤相结合：
- 搜索_作者 -特定作者作品中的语义搜索
- 搜索\_ \_主题 -在标记有特定主题的内容中进行语义搜索
- 搜索_图书 -特定书籍中的语义搜索
- 搜索_页面_范围 -特定页面范围内的语义搜索
- 高级搜索 -具有多个过滤器的语义搜索（作者+书籍+主题+页面）
实用工具
- get_by_id -按ID检索特定文档
- get_index_stats -获取松果指数的统计数据
- 矢量搜索 -使用预先计算的嵌入向量进行搜索（高级）
数据模式
数据库中的每个文档都包含：
{
"id": "Author_BookName_PageNumber",
"score": 0.2712,
"metadata": {
"author_name": "Wassily Leontief",
"book_name": "Leontief_Essays in economics - theories and theorizing_1966",
"chapter_titles": ["Chapter Title"],
"chunk_text": "# Page 70\n...",
"pages": ["70", "71"],
"subjects": ["income", "national income", "output", "price"]
}
}安装
先决条件
- Python 3.10或更高版本
- 具有现有索引的松果账户
- MCP兼容客户端（如克劳德桌面、克劳德代码）
设置
- 克隆或创建项目目录：
mkdir pinecone-econ-mcp
cd pinecone-econ-mcp- 安装依赖项：
pip install -r requirements.txt- 配置环境变量：
复制 .env.example 到 .env 并填写您的凭据：
cp .env.example .env编辑 .env:
PINECONE_API_KEY=your-pinecone-api-key-here
PINECONE_INDEX_NAME=economic-books- 配置MCP客户端：
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"pinecone-econ": {
"command": "/opt/homebrew/bin/python3.10",
"args": ["/absolute/path/to/pinecone-econ-mcp/server.py"]
}
}
}或者克劳德代码(~/.claude.json):
{
"mcpServers": {
"pinecone-econ": {
"command": "/opt/homebrew/bin/python3.10",
"args": ["/absolute/path/to/pinecone-econ-mcp/server.py"]
}
}
}注： 此服务器需要Python 3.10+。如果您的python3.10位于其他位置，请使用 which python3.10 找到它。
用法示例
语义搜索（推荐-默认）
基本语义搜索
# Find content about economic theories using natural language
semantic_search(
query="theories about market equilibrium and price discovery",
top_k=10
)使用作者筛选器进行语义搜索
# Search for "labor productivity" concepts only in Leontief's work
semantic_search_with_filters(
query="labor productivity and input-output relationships",
author_name="Wassily Leontief",
top_k=5
)具有多个过滤器的语义搜索
# Find content about a topic in a specific book
semantic_search_with_filters(
query="national income and economic aggregates",
book_name="Leontief_Essays in economics - theories and theorizing_1966",
subjects=["income", "national income"],
top_k=10
)过滤语义搜索
所有专门的搜索工具都使用语义搜索和元数据过滤相结合。
按作者搜索
# Search for economic concepts within Leontief's works
search_by_author(
query="input output analysis and economic modeling",
author_name="Wassily Leontief",
top_k=10
)按主题搜索
# Search for equilibrium concepts within content tagged "equilibrium"
search_by_subject(
query="price discovery and market clearing mechanisms",
subject="equilibrium",
top_k=15
)按书籍搜索
# Search for specific concepts within a book
search_by_book(
query="national income accounting methodologies",
book_name="Leontief_Essays in economics - theories and theorizing_1966",
top_k=20
)高级搜索
# Semantic search with multiple metadata filters
advanced_search(
query="economic aggregates and measurement theory",
author_name="Wassily Leontief",
subjects=["income", "national income"],
pages=["70", "71", "72"],
top_k=10
)按页面范围搜索
# Search within specific page ranges
search_by_page_range(
query="theoretical foundations of economics",
start_page="50",
end_page="60",
author_name="Wassily Leontief",
top_k=10
)按ID获取文档
# Retrieve a specific document
get_by_id(
document_id="Wassily Leontief_Leontief_Essays in economics - theories and theorizing_1966_27"
)矢量搜索
# Search with a pre-computed embedding vector
vector_search(
vector=[0.1, 0.2, 0.3, ...], # Your embedding vector
top_k=5,
include_metadata=True
)获取索引统计信息
# Get information about the index
get_index_stats()工具详细信息
默认语义搜索
所有搜索工具都使用语义搜索 由Pinecone的综合推理提供动力。只需传递您的文本查询，Pinecone就会自动将其转换为嵌入-不需要手动嵌入调用。这提供了无缝的语义搜索，而不需要管理嵌入模型的复杂性。
只读操作
所有工具都是 只读的 -他们只从松果中查询和检索数据。不公开任何写入、更新或删除操作。
元数据筛选
该服务器使用MongoDB风格的查询运算符将语义搜索与Pinecone的元数据过滤功能相结合：
$eq-等于$in-阵列内$and-逻辑与
结果限制
- 默认
top_k：因工具而异（5-10） - 最大
top_k：每个查询100个结果
命名空间
所有工具支持可选 namespace 多租户松果索引的参数。
建筑
技术栈
- FastMCP：MCP服务器的官方Python SDK
- 松果：用于语义搜索的矢量数据库
- python dotenv：环境变量管理
组件
server.py-主MCP服务器实现requirements.txt-Python依赖关系.env-配置（未提交）.env.example-配置模板
发展
项目结构
pinecone-econ-mcp/
├── server.py # MCP server implementation
├── requirements.txt # Python dependencies
├── .env # Environment variables (create from .env.example)
├── .env.example # Environment template
├── .gitignore # Git ignore rules
└── README.md # This file添加新工具
要添加新的搜索工具，请执行以下操作：
- 使用定义新函数
@mcp.tool()装饰器 - 添加综合文档字符串（用于工具模式）
- 对所有参数使用类型提示
- 返回字符串格式的结果
- 优雅地处理错误
例子：
@mcp.tool()
def my_custom_search(
query_param: str,
top_k: int = 10
) -> str:
"""
Description of what this search does.
Args:
query_param: Description of parameter
top_k: Number of results
Returns:
Description of return value
"""
try:
# Implementation
results = index.query(...)
return str(format_result(results.matches))
except Exception as e:
return f"Error: {str(e)}"故障排除
常见问题
- “找不到API密钥”
- 确保 .env 文件存在并且包含有效 PINECONE_API_KEY - 检查一下 load_dotenv() 正在被呼叫
- “找不到索引”
- 验证 PINECONE_INDEX_NAME 匹配您的松果索引名称 - 检查松果仪表板以确认索引存在
- “未返回任何结果”
- 验证Pinecone索引中是否存在数据 - 检查元数据字段名称是否与数据架构匹配 - 尝试使用 get_index_stats() 验证索引是否有向量
- “找不到模块”
- 跑 pip install -r requirements.txt - 确保你使用的是Python 3.10+
调试模式
直接运行服务器以查看调试输出：
python server.py安全说明
- API密钥：从不承诺
.env文件到版本控制 - 只读的：服务器仅执行读取操作
- 无身份验证：如果对外公开，则添加身份验证
- 速率限制：考虑对生产使用实施速率限制
资源
许可证
MIT许可证-可根据需要自由修改和使用。
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 如果适用，添加测试
- 提交拉取请求
更新日志
v1.0.0（2025-01-12）
- 初始版本
- 10个全面的搜索工具，全部使用语义搜索
- 通过Pinecone集成推理进行语义搜索（直接传递文本，无需手动嵌入）
- 简化的API-
index.search(query="text")对于所有搜索 - Pinecone经济图书数据库的只读访问权限
- 结合语义搜索的高级元数据过滤
- 使用FastMCP实现MCP服务器