Pinecone Read-Only MCP (TypeScript)

A Model Context Protocol (MCP) server that provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.

Features

Hybrid Search: Combines dense and sparse embeddings for superior recall
Semantic Reranking: Uses BGE reranker model for improved precision
Dynamic Namespace Discovery: Automatically discovers available namespaces in your Pinecone index
Metadata Filtering: Supports optional metadata filters for refined searches
Fast & Optimized: Lazy initialization, connection pooling, and efficient result merging
Production Ready: Input validation, error handling, and configurable logging
TypeScript Support: Full TypeScript support with type definitions

Installation

As a Package

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

Or using yarn:

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

Or using pnpm:

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

Global Installation

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

From Source

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

Configuration

The server requires a Pinecone API key and supports the following configuration options:

Environment Variables

Variable	Required	Default	Description
`PINECONE_API_KEY`	Yes	-	Your Pinecone API key
`PINECONE_INDEX_NAME`	No	`rag-hybrid`	Pinecone index name (dense + sparse for hybrid)
`PINECONE_RERANK_MODEL`	No	`bge-reranker-v2-m3`	Reranking model
`PINECONE_READ_ONLY_MCP_LOG_LEVEL`	No	`INFO`	Logging level

Claude Desktop Configuration

Add to your 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"
      }
    }
  }
}

Or with explicit options:

{
  "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"
      ]
    }
  }
}

For a global installation:

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

Usage

Command Line

Run the server using npx (no installation required):

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

Or if installed globally:

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

Or if installed locally in your project:

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

Available Options

--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

Deployment

Production Readiness Defaults

Build now fails fast on TypeScript errors (npm run build no longer suppresses failures).
CI validates typecheck, lint, format, build, smoke run, tests, and package dry-run.
list_namespaces data is cached in-memory for 30 minutes to reduce repeated Pinecone calls.
Query/count flow has guardrails (suggest_query_params before execution) to prevent wasteful calls.

Deploy with npm Package

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

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

Deploy with 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

Release Gate (recommended)

Before tagging/releasing:

npm run release:check

This runs full CI-equivalent checks and validates publish contents with npm pack --dry-run.

API Documentation

The server exposes the following tools via MCP:

`list_namespaces`

Discovers and lists all available namespaces in the configured Pinecone index, including metadata fields and record counts for each namespace.

Parameters: None

Returns: JSON object with namespace details including available metadata fields

metadata_fields values represent inferred field types from sampled records. Common values include: string, number, boolean, string[], and array.

Example response:

{
  "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"
      }
    }
  ]
}

`suggest_query_params`

Suggests which fields to request and which tool to use (count, query_fast, or query_detailed), based on the namespace’s schema (from list_namespaces) and the user’s natural language query. This is a mandatory flow step before count/query tools.

Parameters:

Parameter	Type	Required	Description
`namespace`	string	Yes	Namespace to query (must match a name from `list_namespaces`)
`user_query`	string	Yes	User’s question or intent (e.g. "list papers by John Doe with titles", "how many papers by Wong?")

Returns: suggested_fields (only fields that exist in that namespace), use_count_tool, recommended_tool, explanation, and namespace_found.

Example response:

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

Use suggested_fields as the fields parameter when calling query tools.

`guided_query`

Single orchestrator tool that runs the full flow in one call:

namespace routing (if namespace is omitted),
query param suggestion,
execution via count, query_fast, or query_detailed.

It returns both the final result and a decision_trace for transparency.

Parameters:

Parameter	Type	Required	Default	Description
`user_query`	string	Yes	-	User question/intent
`namespace`	string	No	-	Optional explicit namespace
`metadata_filter`	object	No	-	Optional metadata filter
`top_k`	integer	No	`10`	Query result size for query paths (1-100)
`preferred_tool`	enum	No	`auto`	One of `auto`, `count`, `query_fast`, `query_detailed`
`enrich_urls`	boolean	No	`true`	Auto-generate URLs for `mailing` and `slack-Cpplang` when `metadata.url` is missing

Returns: JSON containing decision_trace and result.

`generate_urls`

Generates URLs for retrieved records when metadata does not contain url and URL is required.

Supported namespaces:

mailing
slack-Cpplang

Rules:

mailing: uses doc_id or thread_id
Format: https://lists.boost.org/archives/list/{doc_id_or_thread_id}/
slack-Cpplang: prefer source directly if present; otherwise use team_id, channel_id, and doc_id
message_id = doc_id.replace('.', '')
Format: https://app.slack.com/{team_id}/{channel_id}/p{message_id}

Parameters:

Parameter	Type	Required	Description
`namespace`	string	Yes	Namespace for URL-generation logic
`records`	array	Yes	Retrieved records; each item can be either metadata itself or an object with `metadata` field

Returns: Per-record generated URL, generation method, and reason if unavailable.

`count`

Returns the unique document count matching a metadata filter and semantic query. Use for questions like "how many papers by John Doe?" instead of the query tool. For performance, the count tool uses semantic (dense) search only (no hybrid or lexical) and requests only document identifiers (document_number, url, doc_id)—no chunk content—then deduplicates by document.

Parameters:

Parameter	Type	Required	Description
`namespace`	string	Yes	Namespace to count in (use `list_namespaces` to discover)
`query_text`	string	Yes	Search query; use a broad term (e.g. `"paper"`, `"document"`) when counting by metadata only
`metadata_filter`	object	No	Same operators as `query` (e.g. `{"author": {"$in": ["John Doe"]}}` for wg21-papers)

Returns: JSON with count (unique documents, up to 10,000), and truncated: true if there are at least 10,000 matches.

Example response:

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

`keyword_search`

Performs keyword (lexical/sparse-only) search over the dedicated sparse index (default: rag-hybrid-sparse, i.e. {PINECONE_INDEX_NAME}-sparse). Use for exact or keyword-style queries. Does not use the dense index or semantic reranking. Call list_namespaces first to discover namespaces; suggest_query_params is optional.

Parameters:

Parameter	Type	Required	Default	Description
`query_text`	string	Yes	-	Search query text (keyword/lexical match)
`namespace`	string	Yes	-	Namespace to search (use `list_namespaces` to discover)
`top_k`	integer	No	`10`	Number of results to return (1-100)
`metadata_filter`	object	No	-	Optional metadata filter (same operators as `query`)
`fields`	string[]	No	-	Optional field names to return; omit for all fields

Returns: JSON with status, query, namespace, index (sparse index name), result_count, and results (ids, metadata, scores). Result rows match the query tool shape (e.g. paper_number, title, author, url, content, score, reranked: false).

Example response:

{
  "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`

Performs hybrid semantic search over the specified namespace in the Pinecone index with optional metadata filtering. For count questions, use the count tool instead.

Parameters:

Parameter	Type	Required	Default	Description
`query_text`	string	Yes	-	Search query text
`namespace`	string	Yes	-	Namespace to search (use `list_namespaces` to discover)
`top_k`	integer	No	`10`	Number of results (1-100)
`use_reranking`	boolean	No	`true`	Enable semantic reranking
`metadata_filter`	object	No	-	Metadata filter to narrow results (e.g., `{"author": "John", "year": 2023}`)
`fields`	string[]	No	-	Field names to return (e.g. `["document_number", "title", "url"]`). Omit for all fields; include `chunk_text` for content. Reduces payload and cost.

Returns: JSON object with search results (only requested fields when fields is set), relevance scores, and metadata

Example response:

{
  "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
    }
  ]
}

Using Metadata Filters:

Metadata filters allow you to narrow down search results based on document properties. First, use list_namespaces to see available metadata fields, then apply filters.

Supported Operators (10 total):

Operator	Syntax	Description	Example
Equal	`$eq` or value directly	Exact match	`{"status": "published"}` or `{"status": {"$eq": "published"}}`
Not Equal	`$ne`	Not equal to	`{"status": {"$ne": "draft"}}`
Greater Than	`$gt`	Greater than	`{"year": {"$gt": 2022}}`
Greater Than or Equal	`$gte`	Greater than or equal	`{"timestamp": {"$gte": 1704067200}}`
Less Than	`$lt`	Less than	`{"score": {"$lt": 0.5}}`
Less Than or Equal	`$lte`	Less than or equal	`{"priority": {"$lte": 3}}`
In Array	`$in`	Value is in array field	`{"tags": {"$in": ["cpp", "contracts"]}}` (only for array-type fields)
Not In Array	`$nin`	Value not in array field	`{"tags": {"$nin": ["draft", "archived"]}}` (only for array-type fields)

Filter Examples:

// 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"]}}

Important Limitations:

String fields require EXACT match - No wildcards, partial matches, or substring searches
Comma-separated strings: If a field contains "John Doe, Herb Sutter", you cannot filter for just "John Doe"
- You must match the entire string: {"author": "John Doe, Herb Sutter"}
- To filter by individual authors, the data must be stored as an array field
$in and $nin operators: Only work on array-type fields, not comma-separated strings
Unsupported operators are rejected: Unknown operators (for example $regex) return a validation error
$in and $nin must use arrays: {"tags": {"$in": "cpp"}} is invalid; use {"tags": {"$in": ["cpp"]}}
Multiple conditions at the top level are combined with AND logic
Use comparison operators ($gt, $gte, $lt, $lte) for numeric and timestamp fields
Direct value assignment implies $eq (exact match)

How It Works

Namespace Discovery: The list_namespaces tool queries your Pinecone index stats to discover available namespaces
Hybrid Search: When querying, the tool searches both dense and sparse indexes in parallel
Result Merging: Results from both indexes are merged and deduplicated
Reranking (optional): The merged results are reranked using a semantic reranker for improved relevance

Development

Setup Development Environment

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

Build

npm run build

Run Tests

npm test

Testing the keyword_search tool

Connectivity and keyword search (script):
Run the search test script (includes a keyword search step against the sparse index):
```
PINECONE_API_KEY=your-key npm run test:search
```
If the sparse index (rag-hybrid-sparse by default) does not exist or has no data, the keyword search step is skipped with a warning.
Via MCP client:
Start the server and call the keyword_search tool with query_text, namespace (from list_namespaces), and optional top_k or metadata_filter. Response shape is the same as the query tool (e.g. results with ids, metadata, scores; reranked is always false).

Code Quality

# 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

Development Server

Run the server in development mode with auto-reload:

npm run dev -- --api-key YOUR_API_KEY

Contribution Guidelines

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Ensure all tests pass: npm test
Ensure code quality checks pass: npm run lint && npm run format:check && npm run typecheck
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature-name
Submit a pull request

Dependencies

Production Dependencies

@modelcontextprotocol/sdk - MCP SDK for TypeScript
@pinecone-database/pinecone - Pinecone client SDK
zod - TypeScript-first schema validation
dotenv - Environment variable management

Development Dependencies

TypeScript - Type-safe JavaScript
ESLint - Code linting
Prettier - Code formatting
Vitest - Testing framework

Comparison with Python Version

This TypeScript implementation provides the same functionality as the Python version with the following benefits:

Native Node.js integration
Better npm ecosystem integration
TypeScript type safety
Similar performance characteristics
Same API interface

Troubleshooting

API Key Issues

If you see "Pinecone API key is required" error:

Ensure PINECONE_API_KEY environment variable is set, OR
Pass --api-key option when running the server

Index Not Found

If you see index-related errors:

Verify your index name is correct
Ensure your API key has access to the index
Check that both your-index-name and your-index-name-sparse indexes exist

Connection Issues

If you experience connection issues:

Check your internet connection
Verify Pinecone service status
Ensure firewall/proxy settings allow connections to Pinecone

License

This project is licensed under the Boost Software License 1.0 - see the LICENSE file for details.

Authors

Will Pak - cppalliance.org

Acknowledgements

This project uses:

Pinecone for vector storage and retrieval
Model Context Protocol for standardized AI integration
Hybrid search approach combining dense embeddings with sparse BM25-style retrieval

Related Projects

Python version - Original Python implementation
Pinecone MCP - Full-featured Pinecone MCP with write capabilities

Support

For issues and questions:

GitHub Issues: https://github.com/CppDigest/pinecone-read-only-mcp-typescript/issues
Email: will@cppalliance.org

Changelog

See CHANGELOG.md for a list of changes in each version.

Name		Name	Last commit message	Last commit date
Latest commit History 110 Commits
.github		.github
scripts		scripts
src		src
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Pinecone Read-Only MCP (TypeScript)

Features

Installation

As a Package

Global Installation

From Source

Configuration

Environment Variables

Claude Desktop Configuration

Usage

Command Line

Available Options

Deployment

Production Readiness Defaults

Deploy with npm Package

Deploy with Docker

Release Gate (recommended)

API Documentation

list_namespaces

suggest_query_params

guided_query

generate_urls

count

keyword_search

query

How It Works

Development

Setup Development Environment

Build

Run Tests

Testing the keyword_search tool

Code Quality

Development Server

Contribution Guidelines

Dependencies

Production Dependencies

Development Dependencies

Comparison with Python Version

Troubleshooting

API Key Issues

Index Not Found

Connection Issues

License

Authors

Acknowledgements

Related Projects

Support

Changelog

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`list_namespaces`

`suggest_query_params`

`guided_query`

`generate_urls`

`count`

`keyword_search`

`query`

Packages