MCP Pinecone Rag

mcp松果抹布

______________________________________________________________________

它的作用

显示单个MCP工具-- rag_query --LLM可以使用 三层检索管道:

User question
  → rag_query tool called by LLM
    → text-embedding-005 (Vertex AI) embeds the query → 768-dim vector
    → Pinecone vector search → top-20 candidate chunks
    → Keyword boost — exact matches for module names, error codes, filenames promoted
    → (Optional) Cross-encoder reranker → final top-K results reordered
    → chunks rendered as compact readable text and returned to LLM
  → LLM synthesizes a grounded answer
  → trajectory entry written to log file (if configured)

______________________________________________________________________

回收管道

三层协同工作以获得更高的精度：

关键字提取规则

与这些模式中的任何一个匹配的令牌都被视为域关键字：

关键字boost被标准化为 [0, 1] 加权为 0.2，所以语义相似性总是占主导地位——当两个结果接近时，关键字只是打破了平衡。

FetchK vs TopK

矢量搜索检索 20名候选人 (FetchK=20)，然后对其进行评分和排名，然后将其调整为所需值 top_k （默认值5）。获取更多的候选词可以提高关键字的效率，并使重新排名的人有更多的工作机会。

______________________________________________________________________

先决条件

松果指数要求

索引必须已填充由生成的嵌入 text-embedding-005 （768个维度）。每个向量应有的元数据字段：

______________________________________________________________________

快速开始

1.克隆和构建

git clone https://github.com/aravindanugonda/mcp-pinecone-rag.git
cd mcp-pinecone-rag
go build -o mcp-pinecone-rag .

2.配置mcp以使用此服务器

在你的 mcp-go config.yaml，添加：

mcp_servers:
  - name: "pinecone-rag"
    type: "stdio"
    command: "/path/to/mcp-pinecone-rag/mcp-pinecone-rag"
    args: []
    env:
      PINECONE_API_KEY: "your-pinecone-api-key"
      GOOGLE_CLOUD_PROJECT: "your-gcp-project-id"
      GOOGLE_APPLICATION_CREDENTIALS: "/path/to/service-account.json"
      VERTEX_AI_LOCATION: "us-central1"
      PINECONE_INDEX_HOST: "your-index-host.svc.aped-xxxx.pinecone.io"
      PINECONE_NAMESPACE: ""
      RAG_TOP_K: "5"
      RERANKER_URL: "http://localhost:8090"        # optional — see Local Reranker below
      TRAJECTORY_LOG_FILE: "/tmp/trajectory.jsonl" # optional — see Trajectory Logging below

______________________________________________________________________

环境变量

\*或使用 gcloud auth application-default login 如果gcloud CLI可用。

______________________________________________________________________

本地排名

reranker是可选的Python服务(reranker.py)使用 快速嵌入 （ONNX运行时——不需要PyTorch）在本地运行交叉编码器模型。它由以下人员自动管理 mcp-host.sh 在主主持人旁边。

重要提示：启动时间

开 首次运行，fastembed下载模型权重（约280 MB bge-reranker-base).这需要30-60秒。在此窗口期间发送的查询将优雅地回退到关键字增强的结果(reranked: false 在轨迹日志中）。在后续启动时，模型将在几秒钟内从缓存中加载。

手动启动

pip install fastembed flask
python3 reranker.py

环境变量

支持的模型

模型文件在首次启动时自动下载并缓存到 ~/.cache/fastembed/.

健康检查

GET http://localhost:8090/health
→ {"model": "BAAI/bge-reranker-base", "status": "ok"}

如果 /health 挂起时，重新登录器仍在处理请求（服务器是多线程的，但CPU推理每批可能需要10-20秒）。请稍候，然后重试。

重新排序延迟

BAAI/bge-reranker-base 在CPU上运行，并独立地对每个（查询、块）对进行评分。对于20名候选人和典型的区块大小，重新排名需要 10-20秒 在现代CPU上。HTTP客户端超时设置为 30秒 为了适应这一点。如果您需要更低的延迟，请减少 RAG_TOP_K 或者切换到较小的型号。

______________________________________________________________________

轨迹记录

当 TRAJECTORY_LOG_FILE 已设置，每 rag_query 调用会附加一个JSON行，记录完整的检索管道执行情况。这是理解和提高检索质量的主要工具。

日志格式（JSON行——每个查询一个对象）

{
  "timestamp": "2026-04-04T03:42:21Z",
  "query": "AMODE 31 64 cross mode calling P64 directive",
  "fetch_k": 20,
  "top_k": 10,
  "retrieved": [
    {"id": "...", "source": "gs://bucket/file.pdf", "score": 0.936},
    ...
  ],
  "final": [
    {"id": "...", "source": "gs://bucket/file.pdf", "score": 5.27},
    ...
  ],
  "reranked": true,
  "latency_ms": 14823
}

retrieved --所有20个松果候选词在关键字增强后，按分数排序。\ final --前K个结果返回给LLM（当以下情况发生时，重新分级分数将替换余弦分数 reranked: true).

有用的jq查询

# Pretty-print all entries
jq . /tmp/trajectory.jsonl

# Last query summary
tail -1 /tmp/trajectory.jsonl | jq '{query, reranked, latency_ms}'

# Check if reranking is working
jq '{query, reranked}' /tmp/trajectory.jsonl

# See how reranker reordered results (compare retrieved vs final source order)
tail -1 /tmp/trajectory.jsonl | jq '{retrieved: [.retrieved[].source], final: [.final[].source]}'

# Watch live
tail -f /tmp/trajectory.jsonl | jq .

______________________________________________________________________

块渲染

松果指数中存储的块为 JSON数组 （例如，来自结构化提取管道）在返回LLM之前会自动转换为紧凑、可读的项目符号线：

• EXEC (JCL Keywords) [Enterprise Developer for Eclipse (UNIX)]: Executes a program, a JCL procedure or a REXX procedure.
• DLBL (JCL Keywords) [Enterprise Developer for Eclipse (UNIX)]: Associates a DD name with a dataset.

纯文本块将原封不动地返回。此转换发生在 internal/server/server.go 并且显著减少了发送到LLM的令牌计数，同时保留了所有相关信息。

______________________________________________________________________

MCP工具： rag_query

说明： 搜索知识库。查询矢量数据库以查找相关文档段落。

输入架构：

______________________________________________________________________

项目结构

.
├── main.go                          # Entry point: env config + stdio read loop
├── reranker.py                      # Local cross-encoder reranker (fastembed + Flask, threaded)
├── internal/
│   ├── embedding/
│   │   └── google.go                # Vertex AI text-embedding-005 client (via ADC)
│   ├── protocol/
│   │   └── types.go                 # MCP JSON-RPC 2.0 protocol types
│   ├── reranker/
│   │   └── local.go                 # HTTP client for local reranker (30s timeout)
│   ├── retriever/
│   │   ├── retriever.go             # 3-layer pipeline: embed → hybrid → rerank
│   │   └── logger.go                # Trajectory logger (JSON lines)
│   ├── server/
│   │   └── server.go                # MCP server + chunk JSON→text rendering
│   └── vectordb/
│       └── pinecone.go              # Pinecone query client
├── go.mod
└── go.sum

______________________________________________________________________

身份验证的工作原理

此服务器使用 应用程序默认凭据（ADC）.何时 GOOGLE_APPLICATION_CREDENTIALS 指向服务帐户JSON密钥时，Vertex AI客户端库会自动拾取它。

服务帐户需要以下之一：

• roles/aiplatform.expressUser --顶点AI平台快速用户（测试版）
• roles/aiplatform.user --顶点AI用户

______________________________________________________________________

MCP协议

实施MCP协议版本 2024-11-05 结束 stdio 运输。与支持stdio服务器的任何MCP主机兼容。

______________________________________________________________________

许可证

麻省理工学院