@dotlab-hq/vector-store-mcp 1.0.0

package/README.md

@@ -0,0 +1,225 @@
+# vector-store-mcp
+
+MCP (Model Context Protocol) server for the **OpenAI Vector Store API**. Manage vector stores, files, file batches, and perform semantic search — all through a single MCP server.
+
+Supports **two transports**:
+
+- **stdio** — for local use with Claude Desktop, VS Code Copilot, or any MCP-compatible client
+- **HTTP (Streamable)** — for deployment as a web service
+
+## Features
+
+- **21 tools** covering the full OpenAI Vector Store API
+- Fully typed with TypeScript + Zod schema validation
+- Uses the official [OpenAI Node SDK](https://github.com/openai/openai-node)
+- Two entry points: local stdio and HTTP server
+- Zero-config for local development
+
+## Installation
+
+```bash
+# Clone and install
+git clone <repo-url>
+cd vector-store-mcp
+npm install
+
+# Build
+npm run build
+```
+
+## Environment Variables
+
+| Variable          | Required | Description                                              |
+| ----------------- | -------- | -------------------------------------------------------- |
+| `OPENAI_API_KEY`  | **Yes**  | Your OpenAI API key                                      |
+| `OPENAI_API_BASE` | No       | Custom OpenAI API base URL (for proxies/compatible APIs) |
+| `PORT`            | No       | HTTP server port (default: `3000`)                       |
+| `HOST`            | No       | HTTP server host (default: `127.0.0.1`)                  |
+
+## Usage
+
+### Local (stdio) — Recommended for Desktop Clients
+
+```bash
+# Run directly
+npm start
+
+# Or with dev watch mode
+npm run dev
+```
+
+### HTTP Server — For Deployment
+
+```bash
+# Start the HTTP server
+npm run start:http
+
+# Or with dev watch mode
+npm run dev:http
+```
+
+The HTTP server exposes:
+
+- `GET /health` — Health check
+- `POST /mcp` — MCP Streamable HTTP endpoint
+- CORS enabled for all origins in development
+
+## Client Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "vector-store": {
+      "command": "node",
+      "args": ["/absolute/path/to/vector-store-mcp/dist/stdio.js"],
+      "env": {
+        "OPENAI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+Add to your VS Code `settings.json` or `.vscode/mcp.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "vector-store": {
+        "command": "node",
+        "args": ["/absolute/path/to/vector-store-mcp/dist/stdio.js"],
+        "env": {
+          "OPENAI_API_KEY": "your-api-key-here"
+        }
+      }
+    }
+  }
+}
+```
+
+### HTTP/Web Clients
+
+With HTTP-based MCP, the **server holds the credentials** — the client only needs the URL. The API key and base URL are passed as environment variables when **starting the server**, not in the client config.
+
+**1. Start the server with your credentials:**
+
+```bash
+# Pass env vars directly
+OPENAI_API_KEY=sk-... npm run start:http
+
+# Or use a .env file / shell profile to set them
+export OPENAI_API_KEY=sk-...
+export OPENAI_API_BASE=https://your-proxy.example.com/v1  # optional
+npm run start:http
+# Server running at http://127.0.0.1:3000/mcp
+```
+
+**2. Connect from your MCP client — just the URL, no keys needed:**
+
+VS Code `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "vector-store": {
+      "url": "http://127.0.0.1:3000/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+Any MCP-compatible HTTP client:
+
+```http
+POST http://127.0.0.1:3000/mcp
+Content-Type: application/json
+```
+
+> **How it works:** The server process reads `OPENAI_API_KEY` from its own environment and uses it for all OpenAI API calls. The MCP client never sees or transmits the key — it just sends tool requests to the server URL. This means you can run the server anywhere (local, cloud, Docker) and point multiple clients at it.
+
+## Programmatic API
+
+You can also use this as a library:
+
+```typescript
+import {
+  McpServer,
+  registerAllTools,
+  getClient,
+  resetClient,
+} from "vector-store-mcp";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+registerAllTools(server);
+```
+
+## Tools (21)
+
+### Vector Stores (6)
+
+| Tool                           | Description                                                    |
+| ------------------------------ | -------------------------------------------------------------- |
+| `openai_create_vector_store`   | Create a new vector store                                      |
+| `openai_retrieve_vector_store` | Retrieve a vector store by ID                                  |
+| `openai_update_vector_store`   | Update a vector store's name or metadata                       |
+| `openai_delete_vector_store`   | Delete a vector store                                          |
+| `openai_list_vector_stores`    | List all vector stores with pagination and filtering           |
+| `openai_search_vector_store`   | Search a vector store with a query string and optional filters |
+
+### Files (4)
+
+| Tool                           | Description                                                  |
+| ------------------------------ | ------------------------------------------------------------ |
+| `openai_list_files`            | List files with filtering by purpose, status, and pagination |
+| `openai_retrieve_file`         | Retrieve file metadata by ID                                 |
+| `openai_delete_file`           | Delete a file by ID                                          |
+| `openai_retrieve_file_content` | Download the content of a file by ID                         |
+
+### Vector Store Files (6)
+
+| Tool                                         | Description                                                |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| `openai_attach_file_to_vector_store`         | Attach a file to a vector store with optional attributes   |
+| `openai_list_vector_store_files`             | List files in a vector store with filtering and pagination |
+| `openai_retrieve_vector_store_file`          | Retrieve a specific file in a vector store                 |
+| `openai_delete_vector_store_file`            | Remove a file from a vector store                          |
+| `openai_retrieve_vector_store_file_content`  | Download file content from a vector store                  |
+| `openai_update_vector_store_file_attributes` | Update attributes on a vector store file                   |
+
+### File Batches (4)
+
+| Tool                                        | Description                                |
+| ------------------------------------------- | ------------------------------------------ |
+| `openai_create_vector_store_file_batch`     | Create a batch of files for a vector store |
+| `openai_retrieve_vector_store_file_batch`   | Retrieve batch status and details          |
+| `openai_cancel_vector_store_file_batch`     | Cancel an in-progress batch                |
+| `openai_list_vector_store_file_batch_files` | List files in a specific batch             |
+
+### Upload (1)
+
+| Tool                 | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `openai_upload_file` | Upload a file to OpenAI (for use with vector stores) |
+
+## npm Scripts
+
+| Script               | Description                     |
+| -------------------- | ------------------------------- |
+| `npm start`          | Run stdio transport (local)     |
+| `npm run start:http` | Run HTTP transport (deployment) |
+| `npm run dev`        | Dev mode with watch (stdio)     |
+| `npm run dev:http`   | Dev mode with watch (HTTP)      |
+| `npm run build`      | Compile TypeScript              |
+| `npm run clean`      | Remove dist/                    |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import OpenAI from "openai";
+/**
+ * Get or create the OpenAI client singleton.
+ * Uses OPENAI_API_KEY and optionally OPENAI_API_BASE from environment.
+ */
+export declare function getClient(): OpenAI;
+/**
+ * Reset the singleton (for testing or re-configuration).
+ */
+export declare function resetClient(): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAI5B;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAmBlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/client.js

@@ -0,0 +1,28 @@
+import OpenAI from "openai";
+let _client = null;
+/**
+ * Get or create the OpenAI client singleton.
+ * Uses OPENAI_API_KEY and optionally OPENAI_API_BASE from environment.
+ */
+export function getClient() {
+    if (_client)
+        return _client;
+    const apiKey = process.env["OPENAI_API_KEY"];
+    if (!apiKey) {
+        throw new Error("OPENAI_API_KEY environment variable is required. " +
+            "Set it to your OpenAI API key before starting the server.");
+    }
+    const baseURL = process.env["OPENAI_API_BASE"];
+    _client = new OpenAI({
+        apiKey,
+        ...(baseURL ? { baseURL } : {}),
+    });
+    return _client;
+}
+/**
+ * Reset the singleton (for testing or re-configuration).
+ */
+export function resetClient() {
+    _client = null;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,IAAI,OAAO,GAAkB,IAAI,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mDAAmD;YACjD,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAE/C,OAAO,GAAG,IAAI,MAAM,CAAC;QACnB,MAAM;QACN,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * vector-store-mcp — programmatic API entry point.
+ *
+ * Import this module to use the MCP server in your own code,
+ * or re-export for custom integrations.
+ */
+export { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+export { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+export { registerAllTools } from "./tools/index.js";
+export { getClient, resetClient } from "./client.js";
+export * from "./schemas/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrD,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * vector-store-mcp — programmatic API entry point.
+ *
+ * Import this module to use the MCP server in your own code,
+ * or re-export for custom integrations.
+ */
+export { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+export { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+export { registerAllTools } from "./tools/index.js";
+export { getClient, resetClient } from "./client.js";
+export * from "./schemas/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrD,cAAc,oBAAoB,CAAC"}