@laskarks/mcp-rag-node 1.0.1

package/README.md

@@ -0,0 +1,181 @@
+# RAG MCP Server
+
+MCP (Model Context Protocol) server for RAG (Retrieval-Augmented Generation) using Pinecone, OpenAI-compatible embedding APIs, and the official MCP SDK. Save documents and search by semantic similarity via MCP tools.
+
+## Tools
+
+| Tool                     | Description                                            |
+| ------------------------ | ------------------------------------------------------ |
+| `save_to_rag`            | Chunk text, create embeddings, and save to Pinecone.   |
+| `search_document_on_rag` | Search documents by keyword using semantic similarity. |
+
+## Installation
+
+```bash
+npm install rag-mcp-nodejs
+# or
+npx rag-mcp-nodejs
+```
+
+## Environment Variables
+
+### Required
+
+| Variable           | Description                                                | Example                                                   |
+| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------- |
+| `APIKEY`           | OpenAI or OpenRouter API key for embeddings                | `sk-...`                                                  |
+| `EMBEDDING_MODEL`  | Embedding model ID                                         | `text-embedding-3-small`, `openai/text-embedding-3-small` |
+| `PINECONE_API_KEY` | Pinecone API key                                           | `...`                                                     |
+| `PINECONE_INDEX`   | Pinecone index name (dimension must match embedding model) | `rag-index`                                               |
+| `PROVIDER`         | AI provider (allowed values: `openai`, `openrouter`)       | `openai` or `openrouter`                                  |
+
+> **Important:** Create your Pinecone index with the same dimension as your embedding model.
+
+### Embedding models and vector dimensions
+
+Use the **Dimension** column when creating your Pinecone index.
+
+| Model                                            | Dimension | Provider                 |
+| ------------------------------------------------ | --------- | ------------------------ |
+| `text-embedding-3-small`                         | 1536      | OpenAI, OpenRouter       |
+| `text-embedding-3-large`                         | 3072      | OpenAI, OpenRouter       |
+| `text-embedding-ada-002`                         | 1536      | OpenAI, OpenRouter       |
+| `text-embedding-3-small` (with dimensions param) | 512–1536  | OpenAI                   |
+| `voyage-3`                                       | 1024      | Voyage (via OpenRouter)  |
+| `nomic-embed-text-v1.5`                          | 768       | Nomic (via OpenRouter)   |
+| `mistral-embed`                                  | 1024      | Mistral (via OpenRouter) |
+| `cohere/embed-english-v3.0`                      | 1024      | Cohere (via OpenRouter)  |
+
+For OpenRouter, use the model ID format, e.g. `openai/text-embedding-3-small` or `voyage/voyage-3`.
+
+### Optional
+
+| Variable               | Description                           | Default |
+| ---------------------- | ------------------------------------- | ------- |
+| `RAG_CHUNK_MAX_TOKENS` | Max tokens per chunk before embedding | `512`   |
+| `RAG_CHUNK_OVERLAP`    | Overlap tokens between chunks         | `50`    |
+
+## Usage
+
+### Run the server
+
+```bash
+npm run build
+npm start
+```
+
+Or with env file:
+
+```bash
+# .env
+APIKEY=sk-...
+EMBEDDING_MODEL=text-embedding-3-small
+PINECONE_API_KEY=...
+PINECONE_INDEX=rag-index
+PROVIDER=openai
+```
+
+```bash
+npm start
+```
+
+### Add to MCP clients
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "rag": {
+      "command": "node",
+      "args": ["/path/to/rag-mcp-nodejs/dist/index.js"],
+      "env": {
+        "APIKEY": "sk-...",
+        "EMBEDDING_MODEL": "text-embedding-3-small",
+        "PINECONE_API_KEY": "...",
+        "PINECONE_INDEX": "rag-index",
+        "PROVIDER": "openai"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json` or MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "rag": {
+      "command": "node",
+      "args": ["/path/to/rag-mcp-nodejs/dist/index.js"],
+      "env": {
+        "APIKEY": "sk-...",
+        "EMBEDDING_MODEL": "text-embedding-3-small",
+        "PINECONE_API_KEY": "...",
+        "PINECONE_INDEX": "rag-index",
+        "PROVIDER": "openai"
+      }
+    }
+  }
+}
+```
+
+### Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run server (from compiled JS)
+npm start
+
+# Run server (dev, from TypeScript)
+npm run dev
+
+# Run sample client
+npm run client
+```
+
+## Project structure
+
+```
+src/
+├── index.ts    # MCP server entry, tools registration
+├── ai.ts       # AI controller (chunking, embeddings, Pinecone)
+├── env.ts      # Environment loading
+└── client.ts   # Example MCP client for testing
+dist/           # Compiled output (after npm run build)
+```
+
+## Publish to npm
+
+Before publishing:
+
+1. Add `files` to `package.json` to include only `dist/` and docs:
+
+```json
+ "files": ["dist", "README.md"]
+```
+
+2. Ensure `npm run build` succeeds and `dist/` is committed or built on publish.
+3. Add `bin` entry for `npx rag-mcp-nodejs` (optional):
+
+```json
+ "bin": { "rag-mcp-nodejs": "dist/index.js" }
+```
+
+Note: MCP servers are usually run via `node dist/index.js`; a `bin` is optional. 4. Set a unique package name (npm may require scoped name, e.g. `@yourname/rag-mcp-nodejs`). 5. Add `repository`, `homepage`, and `engines.node` in `package.json` (optional but recommended).
+
+## Requirements
+
+- Node.js >= 18
+- Pinecone account
+- OpenAI or OpenRouter API key
+
+## License
+
+ISC

package/dist/ai.js

@@ -0,0 +1,149 @@
+import OpenAI from "openai";
+import { encodingForModel } from "js-tiktoken";
+import { Pinecone, } from "@pinecone-database/pinecone";
+import { env } from "./env.js";
+/**
+ * Ai Controller
+ * Contructor parameters
+ * apikey: string
+ * model: string
+ * embeddingModel: string
+ * provider:  "openrouter" | "openai"
+ */
+class AI {
+    // Contructors
+    constructor(args) {
+        // States
+        this.pineconeKey = "";
+        this.embeddingModel = "";
+        this.pineconeIndex = "";
+        this.provider = null;
+        this.embeddingModel = args.embeddingModel;
+        this.provider = args.provider;
+        this.pineconeKey = args.pineconeKey;
+        this.pineconeIndex = args.pineconeIndex;
+        if (args.provider === "openrouter") {
+            this.MCP_AI = new OpenAI({
+                apiKey: args.apikey,
+                baseURL: `https://openrouter.ai/api/v1`,
+                defaultHeaders: {
+                    "HTTP-Referer": "http://localhost:3000",
+                    "X-Title": "OpenRouter RAG",
+                    "Cache-Control": "no-cache, no-store, must-revalidate",
+                    Pragma: "no-cache",
+                    Expires: "0",
+                },
+            });
+        }
+        else {
+            this.MCP_AI = new OpenAI({
+                apiKey: args.apikey,
+                defaultHeaders: {
+                    "Cache-Control": "no-cache, no-store, must-revalidate",
+                    Pragma: "no-cache",
+                    Expires: "0",
+                },
+            });
+        }
+    }
+    // ================================================================================================== //
+    // CHUNK TEXT
+    // ================================================================================================== //
+    chunkByToken(text, maxTokens, overlap) {
+        const defaultMax = env.RAG_CHUNK_MAX_TOKENS
+            ? Number(env.RAG_CHUNK_MAX_TOKENS)
+            : 512;
+        const defaultOverlap = 50;
+        const limit = maxTokens ?? defaultMax;
+        const overlapTokens = overlap ?? defaultOverlap;
+        let model = null;
+        if (this.provider === "openrouter") {
+            model = this.embeddingModel.split("/")[1];
+        }
+        else
+            model = this.provider;
+        const enc = encodingForModel(model);
+        const tokens = Array.from(enc.encode(text));
+        const chunks = [];
+        let start = 0;
+        while (start < tokens.length) {
+            const slice = tokens.slice(start, start + limit);
+            chunks.push(enc.decode(slice));
+            start += limit - overlapTokens;
+        }
+        return chunks;
+    }
+    // ================================================================================================== //
+    // SAVE_TO_RAG
+    // ================================================================================================== //
+    async save_to_rag(content) {
+        try {
+            const chunkText = this.chunkByToken(content);
+            const response = await this.MCP_AI.embeddings.create({
+                model: this.embeddingModel,
+                input: chunkText,
+            });
+            if (response?.data[0]?.object === "embedding") {
+                const pinecone = new Pinecone({
+                    apiKey: env.PINECONE_API_KEY,
+                });
+                const index = pinecone.index(this.pineconeIndex);
+                const vectors = [
+                    {
+                        id: `${Date.now()}`,
+                        values: response.data[0]?.embedding,
+                        metadata: {
+                            text: chunkText[0],
+                            createdAt: new Date().toISOString(),
+                        },
+                    },
+                ];
+                await index.upsert({ records: vectors });
+                return "Document successfully saved!";
+            }
+            else
+                return `${response?.data[0] || "Unexpected error"} `;
+        }
+        catch (error) {
+            return `${error}`;
+            // return error?.error?.message || "Unexpected error!";
+        }
+    }
+    // ================================================================================================== //
+    // SEARCH_DOCUMENT
+    // ================================================================================================== //
+    async search_documents(content) {
+        try {
+            const chunkText = this.chunkByToken(content);
+            const response = await this.MCP_AI.embeddings.create({
+                model: this.embeddingModel,
+                input: chunkText,
+            });
+            if (response?.data[0]?.object === "embedding") {
+                const questionVector = response.data[0].embedding;
+                // search
+                const pinecone = new Pinecone({ apiKey: this.pineconeKey });
+                const index = pinecone.index(this.pineconeIndex);
+                const results = await index.query({
+                    vector: questionVector,
+                    topK: 3,
+                    includeMetadata: true,
+                });
+                return results;
+                // const relevantChunks = results.matches.map((match) => ({
+                //   text: match.metadata?.text as string,
+                //   score: match.score,
+                // }));
+                // const context = relevantChunks.map((c) => c.text).join("\n\n");
+                // return context;
+            }
+            else {
+                return response?.data[0] || "Unexpected error";
+            }
+        }
+        catch (error) {
+            return `${error}` || "Unexpected error";
+        }
+    }
+}
+export default AI;

package/dist/env.js

@@ -0,0 +1,10 @@
+import { config } from "dotenv";
+config();
+export const env = {
+    PINECONE_API_KEY: `${process.env.PINECONE_API_KEY}`,
+    APIKEY: `${process.env.APIKEY}`,
+    EMBEDDING_MODEL: `${process.env.EMBEDDING_MODEL}`,
+    PINECONE_INDEX: `${process.env.PINECONE_INDEX}`,
+    RAG_CHUNK_MAX_TOKENS: `${process.env.RAG_CHUNK_MAX_TOKENS}`,
+    PROVIDER: `${process.env.PROVIDER}`,
+};

package/dist/index.js

@@ -0,0 +1,72 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { config } from "zod";
+import AI from "./ai.js";
+import { env } from "./env.js";
+const PROVIDER_OPTIONS = ["openai", "openrouter"];
+function parseProvider(value) {
+    const v = (value ?? "").toLowerCase();
+    if (v === "openai" || v === "openrouter")
+        return v;
+    throw new Error(`Invalid PROVIDER: "${value}". Must be one of: ${PROVIDER_OPTIONS.join(", ")}`);
+}
+async function main() {
+    config();
+    const provider = parseProvider(env.PROVIDER);
+    const CallAI = new AI({
+        apikey: env.APIKEY,
+        embeddingModel: env.EMBEDDING_MODEL,
+        pineconeIndex: env.PINECONE_INDEX,
+        pineconeKey: env.PINECONE_API_KEY,
+        provider,
+    });
+    const server = new McpServer({
+        name: "rag-mcp-nodejs",
+        version: "1.0.0",
+    });
+    // ================================================================================================================= //
+    // TOOLS
+    // ================================================================================================================= //
+    // 1. SAVE_DOCUMENT ---------------------------------------------------- >
+    server.registerTool("save_document_to_rag", {
+        title: "Save Document To RAG",
+        description: "Save document or information to RAG",
+        inputSchema: {
+            text: z
+                .string()
+                .describe("Document or information that would be save to RAG"),
+        },
+    }, async ({ text }) => {
+        const response = await CallAI.save_to_rag(text);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: response,
+                },
+            ],
+        };
+    });
+    // 2. SEARCH_DOCUMENT ------------------------------------------------ >
+    server.registerTool("search_document_on_rag", {
+        title: "Search Document On RAG",
+        description: "Search Document on RAG with keyword",
+        inputSchema: {
+            keyword: z
+                .string()
+                .describe("Query / keyword that will search on RAG with similarity"),
+        },
+    }, async ({ keyword }) => {
+        const response = await CallAI.search_documents(keyword);
+        return {
+            content: [{ type: "text", text: `${response}` }],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@laskarks/mcp-rag-node",
+  "version": "1.0.1",
+  "description": "Simple MCP RAG server using @modelcontextprotocol/sdk",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "client": "node --loader ts-node/esm src/client.ts"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "sdk"
+  ],
+  "author": "laskarksatria",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laskar-ksatria/rag-mcp-nodejs"
+  },
+  "homepage": "https://github.com/laskar-ksatria/rag-mcp-nodejs#readme",
+  "bugs": {
+    "url": "https://github.com/laskar-ksatria/rag-mcp-nodejs/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@pinecone-database/pinecone": "^7.1.0",
+    "dotenv": "^17.3.1",
+    "js-tiktoken": "^1.0.21",
+    "openai": "^6.27.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/ai.ts

@@ -0,0 +1,155 @@
+import OpenAI from "openai";
+import { encodingForModel, TiktokenModel } from "js-tiktoken";
+import {
+  Pinecone,
+  PineconeRecord,
+  RecordMetadata,
+} from "@pinecone-database/pinecone";
+import { env } from "./env.js";
+
+export type TProvider = "openrouter" | "openai" | null;
+export interface IContructorsPayload {
+  apikey: string;
+  embeddingModel: string;
+  provider: TProvider;
+  pineconeKey: string;
+  pineconeIndex: string;
+}
+
+/**
+ * Ai Controller
+ * Contructor parameters
+ * apikey: string
+ * model: string
+ * embeddingModel: string
+ * provider:  "openrouter" | "openai"
+ */
+class AI {
+  // States
+  private pineconeKey: string = "";
+  private embeddingModel: string = "";
+  private pineconeIndex: string = "";
+  private MCP_AI: OpenAI;
+  private provider: "openrouter" | "openai" | null = null;
+
+  // Contructors
+  constructor(args: IContructorsPayload) {
+    this.embeddingModel = args.embeddingModel;
+    this.provider = args.provider;
+    this.pineconeKey = args.pineconeKey;
+    this.pineconeIndex = args.pineconeIndex;
+    if (args.provider === "openrouter") {
+      this.MCP_AI = new OpenAI({
+        apiKey: args.apikey,
+        baseURL: `https://openrouter.ai/api/v1`,
+        defaultHeaders: {
+          "HTTP-Referer": "http://localhost:3000",
+          "X-Title": "OpenRouter RAG",
+          "Cache-Control": "no-cache, no-store, must-revalidate",
+          Pragma: "no-cache",
+          Expires: "0",
+        },
+      });
+    } else {
+      this.MCP_AI = new OpenAI({
+        apiKey: args.apikey,
+        defaultHeaders: {
+          "Cache-Control": "no-cache, no-store, must-revalidate",
+          Pragma: "no-cache",
+          Expires: "0",
+        },
+      });
+    }
+  }
+
+  // ================================================================================================== //
+  // CHUNK TEXT
+  // ================================================================================================== //
+  chunkByToken(text: string, maxTokens?: number, overlap?: number): string[] {
+    const defaultMax = env.RAG_CHUNK_MAX_TOKENS
+      ? Number(env.RAG_CHUNK_MAX_TOKENS)
+      : 512;
+    const defaultOverlap = 50;
+    const limit = maxTokens ?? defaultMax;
+    const overlapTokens = overlap ?? defaultOverlap;
+
+    let model: TProvider | string = null;
+    if (this.provider === "openrouter") {
+      model = this.embeddingModel.split("/")[1];
+    } else model = this.provider;
+    const enc = encodingForModel(model as TiktokenModel);
+    const tokens = Array.from(enc.encode(text));
+    const chunks: string[] = [];
+    let start = 0;
+    while (start < tokens.length) {
+      const slice = tokens.slice(start, start + limit);
+      chunks.push(enc.decode(slice));
+      start += limit - overlapTokens;
+    }
+    return chunks;
+  }
+
+  // ================================================================================================== //
+  // SAVE_TO_RAG
+  // ================================================================================================== //
+  async save_to_rag(content: string) {
+    try {
+      const chunkText = this.chunkByToken(content);
+      const response = await this.MCP_AI.embeddings.create({
+        model: this.embeddingModel,
+        input: chunkText,
+      });
+      if (response?.data[0]?.object === "embedding") {
+        const pinecone = new Pinecone({
+          apiKey: env.PINECONE_API_KEY as string,
+        });
+        const index = pinecone.index(this.pineconeIndex);
+        const vectors: PineconeRecord<RecordMetadata>[] = [
+          {
+            id: `${Date.now()}`,
+            values: response.data[0]?.embedding,
+            metadata: {
+              text: chunkText[0],
+              createdAt: new Date().toISOString(),
+            },
+          },
+        ];
+        await index.upsert({ records: vectors });
+        return "Document successfully saved!";
+      } else return `${response?.data[0] || "Unexpected error"} `;
+    } catch (error: any) {
+      return `${error}`;
+      // return error?.error?.message || "Unexpected error!";
+    }
+  }
+  // ================================================================================================== //
+  // SEARCH_DOCUMENT
+  // ================================================================================================== //
+  async search_documents(content: string) {
+    try {
+      const chunkText = this.chunkByToken(content);
+      const response = await this.MCP_AI.embeddings.create({
+        model: this.embeddingModel,
+        input: chunkText,
+      });
+      if (response?.data[0]?.object === "embedding") {
+        const questionVector = response.data[0].embedding;
+        // search
+        const pinecone = new Pinecone({ apiKey: this.pineconeKey });
+        const index = pinecone.index(this.pineconeIndex);
+        const results = await index.query({
+          vector: questionVector,
+          topK: 3,
+          includeMetadata: true,
+        });
+        return results;
+      } else {
+        return response?.data[0] || "Unexpected error";
+      }
+    } catch (error) {
+      return `${error}` || "Unexpected error";
+    }
+  }
+}
+
+export default AI;

package/src/env.ts

@@ -0,0 +1,12 @@
+import { config } from "dotenv";
+
+config();
+
+export const env = {
+  PINECONE_API_KEY: `${process.env.PINECONE_API_KEY}`,
+  APIKEY: `${process.env.APIKEY}`,
+  EMBEDDING_MODEL: `${process.env.EMBEDDING_MODEL}`,
+  PINECONE_INDEX: `${process.env.PINECONE_INDEX}`,
+  RAG_CHUNK_MAX_TOKENS: `${process.env.RAG_CHUNK_MAX_TOKENS}`,
+  PROVIDER: `${process.env.PROVIDER}`,
+};

package/src/index.ts

@@ -0,0 +1,93 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { string, z } from "zod";
+import { config } from "zod";
+import AI from "./ai.js";
+import { env } from "./env.js";
+
+const PROVIDER_OPTIONS = ["openai", "openrouter"] as const;
+type ProviderOption = (typeof PROVIDER_OPTIONS)[number];
+
+function parseProvider(value: string | undefined): ProviderOption {
+  const v = (value ?? "").toLowerCase();
+  if (v === "openai" || v === "openrouter") return v;
+  throw new Error(
+    `Invalid PROVIDER: "${value}". Must be one of: ${PROVIDER_OPTIONS.join(", ")}`,
+  );
+}
+
+async function main() {
+  config();
+
+  const provider = parseProvider(env.PROVIDER);
+
+  const CallAI = new AI({
+    apikey: env.APIKEY,
+    embeddingModel: env.EMBEDDING_MODEL,
+    pineconeIndex: env.PINECONE_INDEX,
+    pineconeKey: env.PINECONE_API_KEY,
+    provider,
+  });
+
+  const server = new McpServer({
+    name: "rag-mcp-nodejs",
+    version: "1.0.0",
+  });
+
+  // ================================================================================================================= //
+  // TOOLS
+  // ================================================================================================================= //
+
+  // 1. SAVE_DOCUMENT ---------------------------------------------------- >
+  server.registerTool(
+    "save_document_to_rag",
+    {
+      title: "Save Document To RAG",
+      description: "Save document or information to RAG",
+      inputSchema: {
+        text: z
+          .string()
+          .describe("Document or information that would be save to RAG"),
+      },
+    },
+    async ({ text }: { text: string }) => {
+      const response = await CallAI.save_to_rag(text);
+      return {
+        content: [
+          {
+            type: "text",
+            text: response,
+          },
+        ],
+      };
+    },
+  );
+
+  // 2. SEARCH_DOCUMENT ------------------------------------------------ >
+  server.registerTool(
+    "search_document_on_rag",
+    {
+      title: "Search Document On RAG",
+      description: "Search Document on RAG with keyword",
+      inputSchema: {
+        keyword: z
+          .string()
+          .describe("Query / keyword that will search on RAG with similarity"),
+      },
+    },
+    async ({ keyword }: { keyword: string }) => {
+      const response = await CallAI.search_documents(keyword);
+      return {
+        content: [{ type: "text", text: `${response}` }],
+      };
+    },
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}