内容
# 语义搜索服务 — MCP 服务器
MCP（[模型上下文协议](https://modelcontextprotocol.io)）**只读语义搜索服务器**，适用于 **任何 [Pinecone](https://www.pinecone.io) 索引**。将其连接到 Claude Desktop（或其他 MCP 客户端），用自然语言提问；服务器会嵌入你的查询并返回索引中最相似的记录，附带相似度评分和元数据。
该服务器不绑定特定领域：适用于法律、 技术文档、知识库、支持、RAG 等。**您只需要 Pinecone 密钥和索引**。此存储库 **不包含凭证或数据**。
## 工作原理
1. 接收文本查询。
2. 将查询转换为向量。**默认情况下，由 Pinecone 自己完成**（Pinecone Inference，模型 `multilingual-e5-large`）— 仅需您的 Pinecone 密钥，无需其他密钥。可选地，可以使用 OpenAI（见下文）。
3. 查询您的 Pinecone 索引（`query`、`top_k`、`include_metadata`）。
4. 返回格式化结果（文本 + 元数据 + 相似度）。
> 嵌入模型必须 **与创建索引时使用的模型相同**（相同的模型和维度）。
### 嵌入：Pinecone（默认）或 OpenAI（可选）
- **Pinecone（默认）：** 无需除 Pinecone 密钥之外的其他密钥。
- **OpenAI（可选）：** 仅当您的索引使用 OpenAI 嵌入时。定义 `OPENAI_API_KEY` 和 `EMBED_MODEL=text-embedding-3-large`（或 `-small`）。
## 要求
- Python 3.10+
- 具有已填充索引的 [Pinecone](https://app.pinecone.io) 帐户。
- *(可选)* OpenAI API 密钥，**仅当**您的索引使用 OpenAI 嵌入时。
## 安装
```bash
git clone https://github.com/DerechoVirtual/mcp-pinecone-jurisprudencia.git
cd mcp-pinecone-jurisprudencia
# 依赖项（推荐使用 uv；也支持 pip + venv）
uv venv
uv pip install mcp openai pinecone python-dotenv
# 配置您的密钥
cp .env.example .env # 在 Windows 上：copy .env.example .env
# 编辑 .env 并填写 PINECONE_API_KEY 和 PINECONE_INDEX（其他为可选）
```
## 配置（`.env`）
| 变量 | 必需 | 描述 |
|---|---|---|
| `PINECONE_API_KEY` | ✅ | 您的 Pinecone API 密钥 |
| `PINECONE_INDEX` | ✅ | 默认搜索索引 |
| `EMBED_MODEL` | ❌ | 嵌入模型。默认为 `multilingual-e5-large`（Pinecone） |
| `OPENAI_API_KEY` | ❌ | 仅当您的索引使用 OpenAI 嵌入时 |
| `PINECONE_NAMESPACE` | ❌ | 默认命名空间 |
| `TEXT_FIELD` | ❌ | 包含文本的元数据字段（如果没有，则自动检测） |
| `PINECONE_INDEX_ALIASES` | ❌ | 别名 → 索引的 JSON，例如 `{"docs":"my-index-docs"}` |
## 连接到 Claude Desktop
编辑 `claude_desktop_config.json`
（Windows：`%APPDATA%\Claude\claude_desktop_config.json`，
macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"pinecone-search": {
"command": "/path/to/.venv/Scripts/python.exe",
"args": ["/path/to/server.py"]
}
}
}
```
完全重启 Claude Desktop。`pinecone_search` 工具将会出现。
> **Windows:** Claude Desktop 在保存首选项时将重写此文件，
> 因此请在应用程序 **关闭** 时添加条目，然后再打开（否则可能会覆盖更改）。
## 工具
`pinecone_search(query, index="", top_k=5, namespace="")`
- `query` — 搜索文本（自然语言）。
- `index` — 留空 = 默认索引；接受实际名称或别名。
- `top_k` — 结果数量（1–50，默认为 5）。
- `namespace` — Pinecone 命名空间（可选）。
## 在没有 Claude 的情况下测试
```bash
python -c "import server; print(server.pinecone_search('your query', '', 3))"
```
## 安全
- `.env` 和 `.venv/` 位于 `.gitignore` 中：**永远不要** 上传您的密钥。
- 服务器是 **只读** 的：仅执行 `query`；不插入或删除。
## 许可证
MIT（参见 `LICENSE`）。
