Pinecone Read Only MCP Typescript

松果只读MCP（TypeScript）

](https://www.npmjs.com/package/@will-cppa/pinecone-read-only-mcp) ](https://nodejs.org)  

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

文档

错误响应

当工具发生故障时，MCP工具结果集 isError: trueThe text 内容为JSON匹配 ToolError （解析为 toolErrorSchema 从 @will-cppa/pinecone-read-only-mcp).

成功载荷不变 不 包裹 ToolError.仍在期待的客户 { "status": "error", "message": "..." } 必须迁移到上面的形状。

特性

• 混合搜索：结合密集和稀疏嵌入以提高召回率
• 语义重新排序：使用BGE重新分级模型以提高精度
• 动态命名空间发现：自动发现Pinecone索引中的可用命名空间
• 元数据筛选：支持用于精细搜索的可选元数据过滤器
• 快速预设：延迟初始化、连接池和高效的结果合并；使用 query 工具 preset=fast | detailed | full 权衡延迟与质量（尚未公布基准——将描述视为定性的）。
• 面向生产的默认值：输入验证、错误处理和可配置日志记录（语义版本控制是1.0之前的版本——升级前请查看CHANGELOG）。
• TypeScript支持：完全支持TypeScript和类型定义

安装

Node.js 20.12 或更高版本 是必需的(engines 在 package.json).

作为一个包裹

npm install @will-cppa/pinecone-read-only-mcp

或使用纱线：

yarn add @will-cppa/pinecone-read-only-mcp

或者使用pnpm：

pnpm add @will-cppa/pinecone-read-only-mcp

全球安装

npm install -g @will-cppa/pinecone-read-only-mcp

来源

git clone https://github.com/CppDigest/pinecone-read-only-mcp-typescript.git
cd pinecone-read-only-mcp-typescript
npm install
npm run build

配置

你需要一个 松果API键 以及（默认情况下）a 密集的 索引加匹配 稀疏 指数；看见 docs/CONFIGURATION.md 对于每个环境变量和CLI标志。

快速参考：

跑 pinecone-read-only-mcp --help 对于CLI等效项(--cache-ttl-seconds, --request-timeout-ms, --disable-suggest-flow等等）。

部署模型

服务器使用 进程全局 建议流量闸门的记忆(suggest_query_params 上下文）、命名空间缓存、URL生成器注册表和活动配置。 Stdio MCP（每个节点进程一个客户端） 匹配此模型。如果你嵌入 setupServer 在多租户HTTP传输背后，自己隔离每个会话的这些结构，或者将建议的流保护视为尽最大努力。

自定义URL生成器

命名空间除 mailing 和 slack-Cpplang （或任何名称空间的不同URL规则）可以使用程序化注册——不需要分叉。

导入 registerUrlGenerator 和类型 UrlGeneratorFn / UrlGenerationResult 从 @will-cppa/pinecone-read-only-mcp.注册 额外的 在发出URL的工具运行之前（通常在之后 setupServer 解析配置）。到 替换 内置 mailing 或 slack-Cpplang 发电机，呼叫 registerUrlGenerator 之后 setupServer，因为 setupServer 首先安装默认值。

import {
  registerUrlGenerator,
  setupServer,
  type UrlGenerationResult,
  type UrlGeneratorFn,
} from '@will-cppa/pinecone-read-only-mcp';

const server = await setupServer(config);

const myDocs: UrlGeneratorFn = (metadata): UrlGenerationResult => {
  const id = typeof metadata.doc_id === 'string' ? metadata.doc_id : null;
  return id
    ? { url: `https://docs.example.com/${id}`, method: 'generated.custom' }
    : { url: null, method: 'unavailable', reason: 'doc_id missing' };
};

registerUrlGenerator('product-docs', myDocs);

更完整的嵌入样本存在于 示例/custom-url-generator.ts.

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "pinecone-search": {
      "command": "npx",
      "args": ["-y", "@will-cppa/pinecone-read-only-mcp"],
      "env": {
        "PINECONE_API_KEY": "your-api-key-here"
      }
    }
  }
}

或者使用明确的选项：

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

对于全局安装：

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

用法

命令行

使用npx运行服务器（无需安装）：

npx @will-cppa/pinecone-read-only-mcp --api-key YOUR_API_KEY

或者，如果全局安装：

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

或者，如果在项目中本地安装：

node node_modules/@will-cppa/pinecone-read-only-mcp/dist/index.js --api-key YOUR_API_KEY

可用选项

--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]
--log-level TEXT         Logging level [default: INFO]
--help, -h               Show help message

部署

生产准备默认值

• 立即构建 快速失败 TypeScript错误(npm run build 不再抑制故障）。
• CI验证类型检查、lint、格式化、构建、冒烟运行、测试和打包试运行。
• list_namespaces 数据在内存中缓存30分钟，以减少重复的松果调用。
• 查询/计数流程有护栏(suggest_query_params 在执行之前），以防止浪费的调用。

使用npm包进行部署

# install
npm i @will-cppa/pinecone-read-only-mcp

# run
npx @will-cppa/pinecone-read-only-mcp --api-key YOUR_API_KEY

使用Docker进行部署

# build image
docker build -t pinecone-read-only-mcp:latest .

# run (stdio MCP server)
docker run --rm -i \
  -e PINECONE_API_KEY=YOUR_API_KEY \
  -e PINECONE_INDEX_NAME=rag-hybrid \
  pinecone-read-only-mcp:latest

释放门（推荐）

在标记/发布之前：

npm run release:check

这将运行完整的CI等效检查，并使用验证发布内容 npm pack --dry-run.

API文档

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

list_namespaces

发现并列出配置的Pinecone索引中的所有可用命名空间，包括每个命名空间的元数据字段和记录计数。

参数： 无

退货： JSON对象，包含命名空间详细信息，包括可用元数据字段

metadata_fields 值表示从采样记录中推断出的字段类型。常见值包括： string, number, boolean, string[]，以及 array.

示例响应：

{
  "status": "success",
  "count": 3,
  "namespaces": [
    {
      "name": "namespace1",
      "record_count": 1500,
      "metadata_fields": {
        "author": "string",
        "year": "number",
        "category": "string"
      }
    },
    {
      "name": "namespace2",
      "record_count": 850,
      "metadata_fields": {
        "title": "string",
        "date": "string"
      }
    }
  ]
}

检索工具决策矩阵

在选择重叠的检索工具时使用此选项。 语义vs词汇： 使用 query / query_fast / query_detailed 或 query_documents 用于基于意义的搜索；使用 keyword_search 用于稀疏索引上的精确或关键字样式匹配。 块与整个文档： 使用 query / query_fast / query_detailed 用于排名块；使用 query_documents 当您需要合并完整文档文本时。 单次注射与手动注射： 使用 guided_query 在一次呼叫中运行路由、建议和执行；否则，请致电 suggest_query_params 在门控工具之前。

• query / query_fast / query_detailed --语义块检索。需要 suggest_query_params 首先为目标命名空间调用。
• query_documents --语义搜索，将块重新组合成整个文档。需要 suggest_query_params 首先为目标命名空间调用。
• keyword_search --词汇（仅稀疏）搜索。不需要 suggest_query_params.
• guided_query --将命名空间路由、建议和查询组合到一个调用中；不需要必备工具。
• count --“多少…？”通过语义搜索统计样式。需要 suggest_query_params 使用前（与 query / query_documents).

suggest_query_params

建议 领域 请求以及使用哪条路径(count，或混合查询预设 快 / 详细的 / 满的 --词汇与 query 工具 preset 参数），基于命名空间的模式（来自 list_namespaces)以及用户的自然语言查询。这是之前的强制性流程步骤 count / query 工具。

参数：

退货： suggested_fields （仅存在于该命名空间中的字段）， use_count_tool, recommended_tool, explanation，以及 namespace_found.

示例响应：

{
  "status": "success",
  "suggested_fields": ["document_number", "title", "url", "author"],
  "use_count_tool": false,
  "recommended_tool": "fast",
  "explanation": "User asked for a list or browse; use minimal fields (no chunk_text) for smaller payload and cost.",
  "namespace_found": true
}

使用 suggested_fields 随着 fields 调用查询工具时的参数。

guided_query

单个编排器工具，在一次调用中运行整个流程：

1. 名称空间路由（如果省略名称空间），
2. 查询参数建议，
3. 执行通过 count 或混合动力 query (fast / detailed / full 预设）。

它返回最终结果和 decision_trace 为了提高透明度。

参数：

退货： JSON包含 decision_trace 和 result.

generate_urls

当元数据不包含时，为检索到的记录生成URL url URL是必需的。

支持的命名空间：

• mailing
• slack-Cpplang

规则：

• mailing：使用 doc_id 或 thread_id\

格式： https://lists.boost.org/archives/list/{doc_id_or_thread_id}/

• slack-Cpplang：更喜欢 source 如果存在，直接；否则使用 team_id, channel_id，以及 doc_id\

message_id = doc_id.replace('.', '')\ 格式： https://app.slack.com/client/{team_id}/{channel_id}/p{message_id}

参数：

退货： 每条记录生成的URL、生成方法和原因（如果不可用）。

count

返回 唯一文档计数 匹配元数据过滤器和语义查询。用于诸如“John Doe写了多少篇论文？”之类的问题，而不是 query 工具。为了提高性能，计数工具使用 仅语义（密集）搜索 （无混合或词法），仅请求文档标识符(document_number, url, doc_id)--没有块内容，然后按文档进行重复数据消除。

参数：

退货： JSON格式 count （唯一文件，最多10000份），以及 truncated: true 如果至少有10000场比赛。

示例响应：

{
  "status": "success",
  "count": 42,
  "truncated": false,
  "namespace": "wg21-papers",
  "metadata_filter": { "author": { "$in": ["John Doe"] } }
}

keyword_search

执行 关键字（仅限词法/稀疏） 在专用稀疏索引上搜索（默认值： rag-hybrid-sparse，即。 {PINECONE_INDEX_NAME}-sparse).用于精确或关键字样式的查询。不使用密集索引或语义重排序。呼叫 list_namespaces 首先发现名称空间； suggest_query_params 是可选的。

参数：

退货： JSON格式 status, query, namespace, index （稀疏索引名称）， result_count，以及 results （id、元数据、分数）。结果行与 query 工具形状（例如。 paper_number, title, author, url, content, score, reranked: false).

示例响应：

{
  "status": "success",
  "query": "contracts C++",
  "namespace": "wg21-papers",
  "index": "rag-hybrid-sparse",
  "result_count": 5,
  "results": [
    {
      "paper_number": "P0548",
      "title": "Contracts for C++",
      "author": "John Doe",
      "url": "https://...",
      "content": "...",
      "score": 0.85,
      "reranked": false
    }
  ]
}

query

使用可选的元数据过滤对Pinecone索引中的指定命名空间执行混合语义搜索 计数 问题，使用 count 工具代替。

参数：

退货： 带有搜索结果的JSON对象（仅在以下情况下请求字段 fields 已设置）、相关性得分和元数据

示例响应：

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

使用元数据筛选器：

元数据过滤器允许您根据文档属性缩小搜索结果的范围。首先，使用 list_namespaces 要查看可用的元数据字段，请应用筛选器。

支持的操作员（共10名）：

筛选器示例：

// Exact match (implicit $eq) - works for single-value string fields
{"status": "published"}

// Exact string match - NOTE: requires full exact match
{"author": "John Doe"}  // Only matches if author field is exactly "John Doe"

// Array field contains value (use $in only for array-type fields)
{"tags": {"$in": ["cpp", "contracts"]}}  // Only if tags is stored as an array

// Numeric comparison
{"year": {"$gte": 2023}}

// Timestamp range (papers from last 2 years)
{"timestamp": {"$gte": 1704067200}}

// Multiple conditions on same field
{"score": {"$gt": 0.8, "$lt": 1.0}}
{"timestamp": {"$gte": 1704067200, "$lte": 1735689600}}

// Multiple fields (AND logic)
{
  "year": {"$gte": 2023},
  "status": "published",
  "timestamp": {"$gte": 1704067200}
}

// Array field not in list (only for array-type fields)
{"tags": {"$nin": ["draft", "template"]}}

重要限制：

• 字符串字段需要完全匹配 -无通配符、部分匹配或子字符串搜索
• 逗号分隔字符串：如果字段包含 "John Doe, Herb Sutter"，你不能只过滤 "John Doe"

- 您必须匹配整个字符串： {"author": "John Doe, Herb Sutter"} - 要按单个作者进行筛选，数据必须存储为数组字段

• $in 和 $nin 操作员：仅处理数组类型的字段，不处理逗号分隔的字符串
• 不支持的运算符被拒绝：未知运算符（例如 $regex)返回验证错误
• $in 和 $nin 必须使用数组: {"tags": {"$in": "cpp"}} 无效；使用 {"tags": {"$in": ["cpp"]}}
• 顶层的多种条件与 与 逻辑
• 使用比较运算符($gt, $gte, $lt, $lte)用于数字和时间戳字段
• 直接价值分配意味着 $eq （完全匹配）

运作原理

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

发展

设置开发环境

git clone https://github.com/CppDigest/pinecone-read-only-mcp-typescript.git
cd pinecone-read-only-mcp-typescript
npm install

构建

npm run build

运行测试

npm test

基准测试

使用模拟Pinecone响应测量服务器端处理开销（无需实时API调用，无需API密钥）：

npm run benchmark

该脚本打印一个以毫秒为单位的p50、p95和p99延迟表，并将结果写入 benchmarks/baseline.json.将新运行与已提交的基线进行比较（例如 git diff benchmarks/baseline.json 重新运行命令后）以发现回归。

测试关键字搜索工具

1. 连接和关键字搜索（脚本）：\

运行搜索测试脚本（包括针对稀疏索引的关键字搜索步骤）：

   PINECONE_API_KEY=your-key npm run test:search

如果稀疏索引(rag-hybrid-sparse 默认情况下）不存在或没有数据，则跳过关键字搜索步骤并发出警告。

1. 通过MCP客户端：\

启动服务器并调用 keyword_search 工具与 query_text, namespace （从 list_namespaces)，可选 top_k 或 metadata_filter响应形状与 query 工具（例如。 results 有id、元数据、分数； reranked 总是 false).

代码质量

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Check formatting
npm run format:check

# Format code
npm run format

# Type check
npm run typecheck

开发服务器

在开发模式下运行服务器并自动重新加载：

npm run dev -- --api-key YOUR_API_KEY

贡献指南

1. 分叉存储库
2. 创建要素分支： git checkout -b feature-name
3. 进行更改并添加测试
4. 确保所有测试通过： npm test
5. 确保代码质量检查通过： npm run lint && npm run format:check && npm run typecheck
6. 提交您的更改： git commit -am 'Add some feature'
7. 推到分支： git push origin feature-name
8. 提交拉取请求

依赖项

生产依赖性

• @模型上下文协议/sdk -用于TypeScript的MCP SDK
• @松果数据库/松果 -松果客户端SDK
• 黄道带 -TypeScript第一模式验证
• Dotenv。 -环境变量管理

发展依赖性

• TypeScript -类型安全的JavaScript
• ESLint -代码linting
• 更漂亮 -代码格式
• 维测试 -测试框架

与Python版本的比较

这个TypeScript实现源于 Python 版本 现在公开了其工具表面的严格超集，包括：

• guided_query （带决策跟踪的单呼叫编排器）
• query_documents （从块中重新组装完整文档）
• keyword_search （仅稀疏索引检索）
• namespace_router 和 suggest_query_params （流量引导）
• count 和 generate_urls

其他好处：

• 原生Node.js集成
• 更好的npm生态系统集成
• TypeScript类型安全
• 相似的性能特征

故障排除

API关键问题

如果您看到“Pinecone API密钥是必需的”错误：

1. 确保 PINECONE_API_KEY 环境变量已设置，或
2. 通过 --api-key 运行服务器时的选项

索引未找到

如果您看到与索引相关的错误：

1. 验证您的索引名称是否正确
2. 确保您的API密钥可以访问索引
3. 检查两者 your-index-name 和 your-index-name-sparse 索引存在

连接问题

如果您遇到连接问题：

1. 检查你的网络连接
2. 验证松果服务状态
3. 确保防火墙/代理设置允许连接到Pinecone

许可证

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

作者

• 威尔·帕克 - cppalliance.org

致谢

本项目使用：

• 松果 用于矢量存储和检索
• 模型上下文协议 用于标准化AI集成
• 结合密集嵌入和稀疏BM25风格检索的混合搜索方法

相关项目

• Python 版本 -原始Python实现
• 松果体MCP -具有写入功能的全功能松果MCP

支持

对于问题和疑问：

• GitHub问题：
• 电子邮件：will@cppalliance.org

更新日志

看 更改日志.md 查看每个版本的更改列表。