Pinecone Read Only MCP

松果只读MCP

](https://pypi.org/project/pinecone-read-only-mcp/) ](https://pypi.org/project/pinecone-read-only-mcp/) 

一种模型上下文协议（MCP）服务器，使用混合搜索（密集+稀疏）和重新排序在松果体向量数据库上提供语义搜索。

特性

• 混合搜索：结合密集和稀疏嵌入以提高召回率
• 语义重新排序：使用BGE重新分级模型以提高精度
• 动态命名空间发现：自动发现Pinecone索引中的可用命名空间
• 元数据筛选：支持用于精细搜索的可选元数据过滤器
• 快速和优化：延迟初始化、连接池和高效的结果合并
• 生产就绪：输入验证、错误处理和可配置日志记录

安装

在一个 uv 托管python项目，通过以下方式添加依赖项：

uv add pinecone-read-only-mcp

或者，对于使用 pip 对于依赖关系：

pip install pinecone-read-only-mcp

要在项目中运行服务器，请执行以下操作：

uv run pinecone-read-only-mcp --api-key YOUR_PINECONE_API_KEY

或者在孤立的环境中在全球范围内运行它：

uvx pinecone-read-only-mcp --api-key YOUR_PINECONE_API_KEY

要直接从源代码安装：

git clone https://github.com/iTinkerBell/pinecone-read-only-mcp.git
cd pinecone-read-only-mcp
pip install -e .

配置

服务器需要Pinecone API密钥，并支持以下配置选项：

环境变量

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "pinecone-search": {
      "command": "uvx",
      "args": ["pinecone-read-only-mcp"],
      "env": {
        "PINECONE_API_KEY": "your-api-key-here"
      }
    }
  }
}

或者使用明确的选项：

{
  "mcpServers": {
    "pinecone-search": {
      "command": "uvx",
      "args": [
        "pinecone-read-only-mcp",
        "--api-key", "your-api-key-here",
        "--index-name", "your-index-name",
        "--rerank-model", "bge-reranker-v2-m3"
      ]
    }
  }
}

用法

命令行

服务器可以在两种模式下运行：

标准I/O模式 （默认）：

pinecone-read-only-mcp --api-key YOUR_API_KEY

SSE运输方式 （适用于web应用程序）：

pinecone-read-only-mcp --api-key YOUR_API_KEY --transport sse --port 8000

可用选项

--api-key TEXT        Pinecone API key (or set PINECONE_API_KEY env var)
--index-name TEXT     Pinecone index name [default: rag-hybrid]
--rerank-model TEXT   Reranking model [default: bge-reranker-v2-m3]
--transport [stdio|sse]  Transport type [default: stdio]
--port INTEGER        Port for SSE transport [default: 8000]
--log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]  Logging level [default: INFO]

API文档

服务器通过MCP公开以下工具：

list_namespaces

在配置的Pinecone索引中发现并列出所有可用的命名空间。

参数： 无

退货： 具有可用命名空间和计数的JSON对象

示例响应：

{
  "status": "success",
  "namespaces": ["namespace1", "namespace2", "namespace3"],
  "count": 3
}

query

对Pinecone索引中的指定命名空间执行混合语义搜索。

参数：

退货： 带有搜索结果的JSON对象，包括内容、相关性得分和元数据

示例响应：

{
  "status": "success",
  "query": "your search query",
  "namespace": "namespace1",
  "result_count": 10,
  "results": [
    {
      "paper_number": "DOC-001",
      "title": "Document Title",
      "author": "Author Name",
      "url": "https://example.com/doc",
      "content": "Document content preview...",
      "score": 0.9234,
      "reranked": true
    }
  ]
}

运作原理

1. 命名空间发现：The list_namespaces 该工具查询Pinecone索引统计数据以发现可用的命名空间
2. 混合搜索：查询时，该工具并行搜索密集索引和稀疏索引
3. 结果合并：合并并消除两个索引的重复结果
4. 重排序 （可选）：使用语义重新排序器对合并结果进行重新排序，以提高相关性

依赖项

• anyio（>=4.5.0）
• 点击（>=8.1.8）
• mcp（>=1.6.0）
• 松果体（>=5.0.0）
• python dotenv（>=1.0.0）
• 媒染剂（>=2.0.0）

发展

设置开发环境

git clone https://github.com/iTinkerBell/pinecone-read-only-mcp.git
cd pinecone-read-only-mcp
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

代码质量

# Run linting
uv run ruff check .

# Run formatting check
uv run ruff format --check .

# Run security checks
uv run bandit -r src/

贡献指南

1. 克隆该仓库
2. 创建要素分支： git checkout -b feature-name
3. 提交您的更改： git commit -am 'Add some feature'
4. 推到分支： git push origin feature-name
5. 提交拉取请求

许可证

此项目根据Boost软件许可证1.0获得许可-有关详细信息，请参阅许可证文件。

作者

• 威尔·帕克 - cppalliance.org

致谢

该项目使用Pinecone进行矢量存储和检索。混合搜索方法将密集嵌入与稀疏BM25风格检索相结合，以获得最佳结果。